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

# 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:

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:

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:

{
  "$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:

# 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

# 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.