This document describes the security architecture of the Sentinel Auth, covering transport security, authentication mechanisms, token lifecycle, service-to-service auth, and input validation.

The service applies middleware in a specific order (outermost first):

Request
  |
  v
GlobalRateLimitMiddleware    -- 30 req/min per IP (all endpoints)
  |
  v
SecurityHeadersMiddleware    -- security response headers
  |
  v
SessionMiddleware            -- encrypted session for OAuth2 state
  |
  v
TrustedHostMiddleware        -- Host header validation (production)
  |
  v
CORSMiddleware               -- cross-origin request policy
  |
  v
Rate Limiting (slowapi)      -- per-endpoint request throttling
  |
  v
Application Routes

Every response includes the following headers, set by SecurityHeadersMiddleware:

When COOKIE_SECURE=true (production with HTTPS), the service adds:

Strict-Transport-Security: max-age=63072000; includeSubDomains

This enforces HTTPS for two years and covers all subdomains. Only enable this when your deployment is fully behind TLS.

Starlette's SessionMiddleware provides encrypted, signed cookies used exclusively by Authlib during the OAuth2 authorization code flow. The session stores the state parameter and PKCE code_verifier between the redirect and callback steps.

Configuration:

# Generate a strong secret (required in production)
python -c "import secrets; print(secrets.token_urlsafe(32))"

SESSION_SECRET_KEY=your-generated-secret-here

The default value dev-only-change-me-in-production is intentionally weak and must be replaced before deployment.

When ALLOWED_HOSTS is set to anything other than *, Starlette's TrustedHostMiddleware validates the Host header on every request. This prevents Host header injection attacks used in cache poisoning and password reset exploits.

# Development (disabled)
ALLOWED_HOSTS=*

# Production
ALLOWED_HOSTS=identity.example.com,api.example.com

Cross-Origin Resource Sharing is handled by DynamicCORSMiddleware, which combines static and database-backed origins:

1. Static origins from the CORS_ORIGINS environment variable
2. Dynamic origins extracted from client_apps.redirect_uris in the database — the middleware derives the origin (scheme://host[:port]) from each registered redirect URI

Origins are refreshed from the database on startup.

CORS_ORIGINS=https://app.example.com,https://admin.example.com

The CORS policy allows:

• Origins: Static origins from CORS_ORIGINS + origins derived from registered client app redirect URIs (no wildcards in production)
• Credentials: Enabled (allow_credentials=True) for cookie-based admin auth
• Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
• Headers: Content-Type, Authorization, X-Service-Key

The service uses four authentication tiers, applied depending on the sensitivity and audience of each endpoint:

All tokens are signed with RS256 (RSA + SHA-256) using a private key and verified with the corresponding public key. This allows any service with the public key to validate tokens without contacting the identity service.

Key generation:

openssl genrsa -out keys/private.pem 2048
openssl rsa -in keys/private.pem -pubout -out keys/public.pem

Access token claims:

Admin token claims:

Token lifetimes:

The service implements refresh token rotation with reuse detection, modeled after the approach described in Auth0's documentation:

1. Issuance: When a user authenticates, the service issues an access token and a refresh token. The refresh token's jti is stored in Redis along with a family_id.

2. Rotation: When the client presents a refresh token at POST /auth/refresh, the service:

   • Atomically consumes the token (GETDEL in Redis -- one-time use)
   • Issues a new access + refresh token pair
   • Stores the new refresh token in the same family

3. Reuse detection: If a consumed refresh token is presented again, the service rejects it. This signals potential token theft -- an attacker replaying a stolen token after the legitimate client already rotated it.

4. Family revocation: When theft is detected or a user is deactivated, the service revokes the entire token family by deleting all jti entries in the family set.

Redis key structure:

After a successful OAuth callback, the service issues a short-lived authorization code instead of passing the raw user_id in the redirect URL. This prevents token theft by anyone who knows a user's UUID.

PKCE is mandatory on Sentinel's own auth codes (S256 only). The frontend must generate a code_verifier and code_challenge before initiating login, pass the code_challenge on GET /auth/login/{provider}, and include the code_verifier when exchanging the code at POST /auth/token. This binds the auth code exchange to the original initiator, preventing authorization code interception attacks.

1. The frontend sends code_challenge and code_challenge_method=S256 as query params on the login endpoint
2. The callback generates a cryptographically random code and stores it in Redis with a 5-minute TTL (alongside the code_challenge)
3. The client uses the code to fetch workspaces (GET /auth/workspaces?code=X) — this peeks at the code without consuming it
4. The client exchanges the code for tokens (POST /auth/token with {code, workspace_id, code_verifier}) — Sentinel verifies SHA256(code_verifier) == code_challenge, then consumes the code atomically via GETDEL
5. A consumed code cannot be reused; a second exchange attempt returns 400

Redis key structure:

Access tokens can be revoked before expiration (e.g., on logout) using a Redis denylist:

1. Client calls POST /auth/logout with the access token in the Authorization header
2. The service extracts the jti and exp from the token
3. The jti is added to the denylist with a TTL equal to the token's remaining lifetime
4. On every authenticated request, the get_current_user dependency checks the denylist

Redis key structure:

This approach keeps the denylist small -- entries automatically expire when the token would have expired anyway.

Admin tokens follow the same denylist pattern as access tokens. When an admin logs out via POST /auth/admin/logout:

1. The endpoint requires a valid admin cookie (Depends(require_admin))
2. The jti from the admin token is added to the Redis denylist
3. The admin_token cookie is deleted from the response
4. On subsequent requests, require_admin checks the denylist before granting access

User logout (POST /auth/logout) performs two actions:

1. Blacklists the access token — adds jti to the Redis denylist
2. Revokes all refresh token families — calls revoke_all_user_tokens(user_id) to invalidate every refresh token the user has, preventing an attacker with a captured refresh token from obtaining new access tokens after the user logs out

Backend services authenticate to the identity service using the X-Service-Key header. This is used for permission and role operations where a service acts autonomously or on behalf of a user.

Service API keys are managed through the service apps system in the admin panel (/admin/service-apps), not environment variables. Each service app has:

• name — human-readable label
• service_name — the service this key is scoped to (verified by verify_service_scope())
• key_hash — SHA-256 hash of the plaintext key (the plaintext is shown once at creation)
• key_prefix — first few characters for identification (e.g., sk_abc1****)
• is_active — can be deactivated without deletion

Keys are validated by service_app_service.validate_key(), which checks the SHA-256 hash against active service apps (with Redis caching).

Dev mode is intentionally permissive: when no active service apps exist in the database, the require_service_key dependency passes through all requests. This allows local development without configuring keys. In production, register at least one service app via the admin panel.

Some endpoints require both a service key and a user JWT. This pattern is used when a service needs to perform an action on behalf of a specific user -- the service key authenticates the calling service, and the JWT identifies the user:

POST /permissions/check
X-Service-Key: sk_prod_abc123
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

The admin panel uses HttpOnly cookies for session management. Cookie attributes are configured for defense in depth:

# Development (HTTP)
COOKIE_SECURE=false

# Production (HTTPS)
COOKIE_SECURE=true

When COOKIE_SECURE=true, the Secure flag ensures the cookie is only sent over HTTPS connections. Additionally, this flag enables HSTS headers on all responses.

Rate limiting uses two layers:

1. Global rate limit — GlobalRateLimitMiddleware enforces 30 requests/minute per IP across all endpoints (except /health). This is a simple in-memory sliding window that catches broad abuse regardless of endpoint.

2. Per-endpoint limits — slowapi applies stricter limits on sensitive endpoints. These fire before the global limit.

When a client exceeds either limit, the service responds with 429 Too Many Requests and a Retry-After header.

Rate limit state is keyed by the client's remote IP address. If the service is behind a reverse proxy, ensure X-Forwarded-For is configured correctly so the real client IP is used.

PKCE prevents authorization code interception attacks. The service uses S256 (SHA-256) code challenge method on providers that support it:

PKCE is configured at the Authlib client registration level via code_challenge_method="S256". Authlib automatically generates the code_verifier and code_challenge, storing the verifier in the session for validation during the callback.

Applications must be registered as client apps before they can use Sentinel. Each client app defines a set of allowed redirect URIs. Sentinel proxies authentication from external IdPs and validates that the redirect_uri belongs to an active registered app.

• GET /auth/login/{provider} requires a redirect_uri that is registered on an active client app
• Only pre-approved redirect URIs can receive authorization codes

This prevents:

• Unauthorized usage — unregistered applications cannot initiate login flows or obtain tokens
• Open redirector attacks — the callback can only redirect to pre-approved URIs

Client apps can be deactivated without deletion to temporarily block an application.

All OAuth2 flows use the state parameter (managed by Authlib via SessionMiddleware) to prevent CSRF attacks during the authorization code exchange. The state is generated on redirect, stored in the encrypted session cookie, and validated on callback.

All request bodies are validated with Pydantic models. Invalid input is rejected with a 422 Unprocessable Entity response before reaching any business logic. This includes:

• Type checking and coercion
• UUID format validation
• Enum value constraints (e.g., workspace roles, permission actions)
• Required vs. optional field enforcement

CSV import endpoints (used by the admin panel) enforce a 5 MB file size limit to prevent denial-of-service via large uploads.

All security-related environment variables:

The pentest/ directory contains a comprehensive security testing suite combining industry-standard tools with custom scripts.

# Install tools (one-time)
make pentest-setup

# Run everything
make pentest

# Custom scripts only (no external tools)
make pentest-custom

# Single tool
cd pentest && python run_all.py --nuclei

Ten test suites covering ~110 individual tests:

All output is saved to pentest/reports/:

• summary.json — combined results from all tools and custom scripts
• zap_report.json, nuclei_findings.jsonl, nikto_report.json, jwt_tool_results.txt

Before deploying to production, verify the following:

• SESSION_SECRET_KEY is set to a cryptographically random value (not the default)
• At least one service app is registered via the admin panel (/admin/service-apps) with a strong key
• COOKIE_SECURE=true and the service is behind TLS
• ALLOWED_HOSTS is set to your actual domain(s), not *
• CORS_ORIGINS lists only your frontend origin(s)
• RS256 key pair is generated and JWT_PRIVATE_KEY_PATH / JWT_PUBLIC_KEY_PATH point to the correct files
• The private key file has restrictive permissions (chmod 600)
• DEBUG=false to disable OpenAPI docs (/docs, /redoc, /openapi.json)
• ADMIN_EMAILS is set if you want auto-promotion for specific users
• A reverse proxy (nginx, Caddy, or cloud LB) handles TLS termination and sets X-Forwarded-For
• Redis is password-protected and not exposed to the public internet
• PostgreSQL uses strong credentials and is not exposed to the public internet