nexus-5-auth/README.md

# Nexus 5 Auth

Enterprise authentication infrastructure for the Nexus 5 platform using Ory Kratos for identity management and Ory Oathkeeper for API gateway/authorization.

## Overview

This repository contains the authentication stack configuration for Nexus 5:

- **nexus-5-auth-kratos**: Ory Kratos identity server configuration
- **nexus-5-auth-oathkeeper**: Ory Oathkeeper API gateway configuration
- **nexus-5-auth-frontend**: SvelteKit-based authentication UI

## Why Ory?

### Improvements Over Previous Auth Approaches

| Feature | Nexus 1-3 (JWT) | Nexus 4 (Rust JWT) | Nexus 5 (Ory) |
|---------|-----------------|--------------------| --------------|
| **Identity Management** | Django User model | Custom User entity | Dedicated identity server |
| **Session Management** | Stateless JWT | Stateless JWT | Server-side sessions |
| **MFA Support** | None | None | Built-in TOTP/WebAuthn |
| **Password Recovery** | Custom implementation | Custom implementation | Built-in flows |
| **Email Verification** | Custom implementation | None | Built-in flows |
| **Admin UI** | Django Admin | None | Full admin capabilities |
| **API Protection** | Middleware checks | Middleware checks | Zero-trust gateway |

### Key Benefits

1. **Security**: Battle-tested, open-source identity infrastructure
2. **Separation of Concerns**: Auth logic separate from business logic
3. **Scalability**: Stateless gateway, horizontally scalable identity server
4. **Standards Compliance**: OAuth2, OpenID Connect ready
5. **Self-Hosted**: Full control over identity data

## Architecture

```
                                    ┌─────────────────┐
                                    │   Auth Frontend │
                                    │   (SvelteKit)   │
                                    └────────┬────────┘
                                             │
                                             ▼
┌─────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client    │───▶│   Oathkeeper    │───▶│     Kratos      │
│  (Browser)  │    │  (API Gateway)  │    │ (Identity Mgmt) │
└─────────────┘    └────────┬────────┘    └─────────────────┘
                            │
                            ▼
                   ┌─────────────────┐
                   │   Nexus 5 API   │
                   │    (Django)     │
                   └─────────────────┘
```

## Components

### Ory Kratos (`nexus-5-auth-kratos/`)

Identity management server handling:
- User registration and login
- Password recovery
- Email verification
- Profile management
- Session management

**Key Files:**
- `config/kratos.yml` - Main Kratos configuration
- `config/identity.schema.json` - User identity schema
- `courier-templates/` - Email templates

### Ory Oathkeeper (`nexus-5-auth-oathkeeper/`)

API gateway providing:
- Request authentication
- JWT token injection for backend services
- Access rule management
- Zero-trust API protection

**Key Files:**
- `config/oathkeeper.yml` - Main Oathkeeper configuration
- `config/access-rules/*.yml` - Route-specific access rules

### Auth Frontend (`nexus-5-auth-frontend/`)

SvelteKit application providing:
- Login/Registration forms
- Password recovery flow
- Email verification flow
- Profile settings
- Admin identity management

## Quick Start

### Prerequisites
- Docker and Docker Compose
- Node.js 18+ (for frontend development)

### Development Setup

```bash
# Start Kratos
cd nexus-5-auth-kratos
docker-compose up -d

# Start Oathkeeper
cd ../nexus-5-auth-oathkeeper
docker-compose up -d

# Start Frontend
cd ../nexus-5-auth-frontend
npm install
npm run dev
```

### Configuration

#### Kratos Configuration

Edit `nexus-5-auth-kratos/config/kratos.yml`:

```yaml
serve:
  public:
    base_url: https://auth.example.com
  admin:
    base_url: http://kratos:4434

selfservice:
  default_browser_return_url: https://app.example.com

courier:
  smtp:
    connection_uri: smtp://user:pass@smtp.example.com:587
```

#### Oathkeeper Configuration

Edit `nexus-5-auth-oathkeeper/config/oathkeeper.yml`:

```yaml
serve:
  proxy:
    port: 4455
  api:
    port: 4456

authenticators:
  cookie_session:
    config:
      check_session_url: http://kratos:4433/sessions/whoami

authorizers:
  allow:
    enabled: true

mutators:
  header:
    enabled: true
    config:
      headers:
        X-User-Id: "{{ print .Subject }}"
```

## Identity Schema

The identity schema defines user attributes:

```json
{
  "$id": "https://example.com/identity.schema.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "type": "object",
  "properties": {
    "traits": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "title": "Email"
        },
        "name": {
          "type": "object",
          "properties": {
            "first": { "type": "string" },
            "last": { "type": "string" }
          }
        }
      },
      "required": ["email"]
    }
  }
}
```

## Access Rules

Access rules define how requests are authenticated and authorized:

```yaml
# Django API protected routes
- id: "django:graphql"
  upstream:
    url: "http://nexus-api:8000"
  match:
    url: "https://api.example.com/graphql/<**>"
    methods: ["POST", "OPTIONS"]
  authenticators:
    - handler: cookie_session
  authorizer:
    handler: allow
  mutators:
    - handler: header
```

## Email Templates

Customize email templates in `nexus-5-auth-kratos/courier-templates/`:

- `verification_code_valid.email.*.gotmpl` - Email verification
- `recovery_code_valid.email.*.gotmpl` - Password recovery
- `recovery_valid.email.*.gotmpl` - Recovery link

## Frontend Routes

The auth frontend provides these routes:

- `/login` - User login
- `/registration` - New user registration
- `/recovery` - Password recovery
- `/verification` - Email verification
- `/settings` - Profile settings
- `/admin` - Identity administration

## Production Deployment

### Security Checklist

1. Generate strong secrets for Kratos and Oathkeeper
2. Use HTTPS for all endpoints
3. Configure secure cookie settings
4. Set up proper CORS origins
5. Enable rate limiting
6. Configure email delivery (SMTP or API)
7. Set up database backups for Kratos

### Environment Variables

```bash
# Kratos
KRATOS_DSN=postgres://user:pass@host:5432/kratos
KRATOS_SECRETS_DEFAULT=your-32-char-secret
KRATOS_SECRETS_COOKIE=your-32-char-cookie-secret

# Oathkeeper
OATHKEEPER_MUTATOR_ID_TOKEN_JWKS_URL=file:///etc/jwks.json

# Frontend
PUBLIC_KRATOS_URL=https://auth.example.com
```

## Related Repositories

- **nexus-5**: Main Django API server
- **nexus-5-frontend-***: Application frontends
- **nexus-5-emailer**: Email microservice
- **nexus-5-scheduler**: Calendar integration

## License

MIT License - See LICENSE file for details.