Auth Service

The Auth Service handles authentication and identity for AEGIS. It verifies email/password credentials, issues JWT tokens, resolves roles and permissions fresh from the database (R42a), and owns the user lifecycle (admin CRUD, invites, password resets).

Overview

AEGIS uses a two-step authentication flow:

1. The client authenticates with an email and password via the auth service, receiving a JWT token (the response also server-sets the aegis_token cookie since R42a)
2. All subsequent requests include the JWT token in the Authorization: Bearer header (or the aegis_token cookie)
3. The API gateway validates the JWT locally (using the shared secret) and extracts user identity

The JWT carries identity; authorization state (roles, permissions, is_active, token version) is re-resolved from the database at the perimeter via POST /auth/resolve — one codepath (resolve_user()) backs both /auth/resolve and /auth/forward-auth, with a ~5s per-user cache. Role changes and deactivation therefore take effect on live traffic within seconds, not at next login.

Users are stored in the PostgreSQL users table, with role grants in user_roles → roles (R42e dropped the legacy users.roles shadow array — grants live solely in user_roles). Passwords are hashed with bcrypt. Accounts are admin-provisioned — there is no self-serve signup — and deactivate-only: there is no hard-delete path. In production the JWT secret would come from HashiCorp Vault.

Port & Language

Key Endpoints

Architecture

src/auth_service/
├── __init__.py
├── main.py            # App wiring, /auth/token, /auth/resolve, forward-auth, directory
├── migrate.py         # Boot-time idempotent migration runner (also `python -m auth_service.migrate`)
├── migrations/        # 001_users, 002_user_tenant, 003_rbac_substrate (all catalog-guarded)
├── rbac.py            # SYSTEM_ROLES + Appendix C PERMISSION_MATRIX + seeds + backfill
├── system_users.py    # R42e: system-user + identity_map seeds, users.roles column drop
├── resolve.py         # Resolver: JWT → DB-fresh identity/roles/permissions (5s cache)
├── tokens.py          # JWT mint/decode (tv claim) + cookie helpers (env-gated attributes)
├── deps.py            # get_repo / get_resolver / require_permission dependencies
├── session_routes.py  # /auth/me, refresh, logout(-all), public invite validate/redeem
├── admin_routes.py    # /auth/admin/users CRUD + invite/reset issuance
├── users.py           # UserRepo (users + user_roles)
├── invites.py         # InviteRepo (sha256-at-rest one-time tokens)
├── security.py        # bcrypt hash/verify
└── create_user.py     # CLI for provisioning/rotating users (+ --deactivate/--reactivate)

Migration runner (R42a)

The service applies every file in src/auth_service/migrations/ in order on every boot — there is no applied-tracking, so every DDL statement is catalog-predicate-guarded and every data migration converges to a no-op on re-run. Seeds (4 system roles, the permission matrix, a one-time backfill of user_roles from the legacy users.roles array, and — R42e — the four system users plus the identity_map seed rows) run after the SQL; once the backfill has run, the runner drops the users.roles shadow column (R42e). The CI job auth-service-tests runs ci/auth_double_boot.sh (boot → boot again → schema + seed state must be identical) to guard the idempotency invariant.

Authentication Flow

1. Client sends POST /auth/token with { "email": "...", "password": "..." }
2. Auth service looks up the user by LOWER(email)
3. Verifies the password against the stored bcrypt hash
4. If valid and active, generates a JWT with user_id, email, roles, and 24-hour expiry
5. Returns the token, expiry, and user info
6. Client stores the token and uses it for all subsequent requests

Invalid credentials or an inactive user return 401 Unauthorized with {"detail": "Invalid email or password"}. Email matching is case-insensitive.

JWT Token Structure

The JWT payload contains:

{
  "user_id": "9b2f1c4e-...",
  "email": "admin@aegis.local",
  "display_name": "Bootstrap Admin",
  "roles": ["admin", "operator", "reviewer"],
  "tenant_id": "00000000-0000-0000-0000-000000000001",
  "tv": 0,
  "iss": "aegis-auth",
  "iat": 1712793600,
  "exp": 1712880000
}

Tokens are signed with HS256 using the JWT_SECRET environment variable.

Users Table

Users live in the PostgreSQL users table:

The RBAC companion tables (R42a, owned by this service’s migration runner — no other service may FK to them):

The users table is created in infrastructure/docker/postgres/init.sql for fresh databases; the auth-service migration runner re-ships it idempotently (migrations/001 / 002) so a fresh DB converges on boot without manual psql.

System users (R42e): the boot seed converges four non-loginable accounts — system@aegis.local (the nil UUID, the SYSTEM_USER literal seeds have always stamped), legacy@aegis.local (backfill target for unmappable pre-R42 identity strings), eval-runner@aegis.local (only inserted if the email is absent), and demo-seed@aegis.local. Empty password_hash fails closed at login; is_active=true so they satisfy the R42e FKs and appear in attribution joins. It also converges the identity_map rows that resolve legacy TEXT actor ids at read time.

Provisioning Users

There is no signup endpoint. The primary path is the Users & Roles admin page at /admin/users (R42d — see the user guide), which drives the admin API: POST /auth/admin/users returns a one-time invite URL (7-day expiry); the invitee opens it, chooses a password, and is logged in. The CLI remains as an ops fallback:

cd services/auth-service
poetry run python -m auth_service.create_user \
  --email alice@example.com \
  --roles admin,operator,reviewer

The command prompts for a password, or reads it from AEGIS_NEW_USER_PASSWORD. Re-running it for an existing email rotates that user’s password (and bumps token_version, revoking live sessions). --deactivate / --reactivate toggle account status — accounts are deactivate-only, never deleted; the CLI refuses to deactivate the last active admin.

Bootstrap Admin

On startup the service seeds an initial admin from BOOTSTRAP_ADMIN_EMAIL and BOOTSTRAP_ADMIN_PASSWORD if a user with that email does not already exist. For local development these default to admin@aegis.local / aegis-dev-admin.

Token Validation

The /auth/validate endpoint decodes and verifies a JWT token:

1. Strip the Bearer prefix if present
2. Decode using PyJWT with the HS256 algorithm and the shared JWT_SECRET
3. Return valid: true with the user’s identity, or valid: false if the token is invalid or expired

This endpoint is used internally by the API gateway, though the gateway also validates tokens locally using its own Go JWT library. The /auth/forward-auth endpoint performs the same check but is method-agnostic and reads the aegis_token cookie or a Bearer header, for use by the Caddy reverse proxy.

Dependencies

Python Packages

Infrastructure Dependencies

PostgreSQL — the auth service reads and writes the users table.

Configuration

The service binds to 0.0.0.0:8009 by default (hardcoded in __main__).

Running Locally

cd services/auth-service
poetry install
poetry run uvicorn auth_service.main:app --reload --port 8009

Testing the Auth Flow

# Step 1: Exchange email + password for a JWT token
curl -X POST http://localhost:8009/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@aegis.local", "password": "aegis-dev-admin"}'
 
# Response:
# {
#   "access_token": "eyJhbGciOiJIUzI1NiIs...",
#   "token_type": "bearer",
#   "expires_in": 86400,
#   "user_id": "dev-user",
#   "roles": ["admin", "operator", "reviewer"]
# }
 
# Step 2: Use the token in subsequent requests
curl http://localhost:8000/api/v1/conversations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."