Authentication & Authorization Architecture

Backend (Confidential Client)

• Holds the client_secret — never exposed to the browser
• Uses openid-client (v6.x) for OIDC discovery, code exchange, and token refresh
• Uses passport-jwt for cookie-first JWT validation (Bearer header fallback)
• PKCE state stored in HttpOnly cookie (2-minute TTL)
• Tokens set as HttpOnly, Secure, SameSite=Lax cookies — never exposed to JavaScript
• CSRF protection via double-submit cookie pattern (CsrfGuard)

Frontend (Stateless SPA)

• No OIDC client library — relies entirely on the backend
• Cookie-based authentication — tokens managed by the browser automatically
• User profile loaded from GET /api/auth/me endpoint on mount
• Axios 401 interceptor with single-flight cookie refresh
• CSRF token read from non-HttpOnly cookie and sent as X-CSRF-Token header

1. Proactive Timer

A setTimeout is scheduled at 75% of the access token's lifetime (minimum 10 seconds). When it fires, the SPA calls POST /api/auth/refresh. Cookies are refreshed automatically by the server response, and the timer is rescheduled.

2. Tab Visibility Listener

When the user returns to the tab (via a visibilitychange event), the SPA checks if the access token has less than 60 seconds remaining. If so, it triggers an immediate refresh to avoid making API calls with an about-to-expire token.

3. Axios 401 Interceptor

If a request returns 401 Unauthorized, the interceptor attempts a single-flight refresh via POST /api/auth/refresh (cookies sent automatically), retries the original request, and only logs the user out if refresh fails.

System Admin (is_system_admin)

A boolean flag on the User database table. System admins bypass all group membership checks and can access all resources. Checked via @Identity({ requireSystemAdmin: true }) or through the pre-populated resolvedIdentity.isSystemAdmin flag.

Group Role (GroupRole)

A per-group role stored in the UserGroup join table. Two levels: MEMBER (default) and ADMIN. Checked via @Identity({ groupIdFrom: ..., minimumRole: GroupRole.ADMIN }) or through resolvedIdentity.groupRoles. API keys are always assigned MEMBER role within their scoped group.

Standard JWT-protected (most common)

@Identity()
@Get("documents")
listDocuments() {}

Requires valid JWT. API keys rejected. Identity enriched with isSystemAdmin and groupRoles for downstream use.

Dual auth — JWT or API key

@Identity({ allowApiKey: true })
@Post("upload")
uploadDocument() {}

Accepts either JWT or X-API-Key. If neither → 401. CSRF automatically exempted for API key and Bearer requests.

System admin only

@Identity({ requireSystemAdmin: true })
@Delete("admin/users/:id")
deleteUser() {}

Requires valid JWT and system-admin status. API keys always fail this check. Non-admins get 403.

Group-scoped with minimum role

@Identity({
  groupIdFrom: { param: "groupId" },
  minimumRole: GroupRole.ADMIN,
})
@Put(":groupId/settings")
updateGroupSettings() {}

Extracts groupId from the route param, verifies membership, and requires at least ADMIN role within that group. System admins bypass these checks.

How It Works

• API keys are generated and managed through the platform Settings page
• Each group can have one active key at a time — keys are scoped to the group, not individual users
• Keys are validated by the ApiKeyAuthGuard via ApiKeyService
• On validation, request.apiKeyGroupId is set to the key's owning group ID, and request.user is populated with roles inherited from the creating user's JWT at key creation time
• The IdentityGuard then sets request.resolvedIdentity = { isSystemAdmin: false, groupRoles: { [groupId]: MEMBER } } for downstream authorization — no database queries required
• Regenerating a key creates a fresh key for the same group

When to Use

• Automated pipelines and CI/CD
• Service-to-service integrations
• Scripts and CLI tools
• Any headless (non-browser) consumer

getIdentityGroupIds(identity)

Returns the list of group IDs the identity can access, or undefined for system-admins (unrestricted access). Used by list/query endpoints to filter results to the requestor's groups. No additional database queries — uses pre-populated groupRoles.

• API key → keys of identity.groupRoles
• System admin (isSystemAdmin: true) → undefined (no filter)
• Regular user → keys of identity.groupRoles

identityCanAccessGroup(identity, groupId, minimumRole?)

Asserts that the identity can access a specific group with an optional minimum role check. Throws HTTP exceptions on failure. Used by single-resource endpoints (get, update, delete) after fetching the resource's group_id. No additional database queries — uses pre-populated groupRoles.

• groupId === null → 404 Not Found (orphaned record)
• No identity → 403 Forbidden
• System admin (isSystemAdmin: true) → always allowed
• Group not in groupRoles → 403 Forbidden
• Role below minimumRole → 403 Forbidden

PKCE (Proof Key for Code Exchange)

The backend generates a code_verifier (random string) and sends its SHA-256 hash (code_challenge) to Keycloak. On callback, the original code_verifier is sent with the code exchange — Keycloak verifies the hash matches, preventing authorization code interception attacks.

Nonce Validation

A random nonce is included in the authorization request and embedded in the ID token by Keycloak. The openid-client library validates that the ID token nonce matches the expected value, ensuring the token was issued for this specific request.

JWKS Signature Verification

All access tokens (from cookies or Bearer headers) are verified using Keycloak's RS256 public keys fetched from the JWKS endpoint via openid-client.

HttpOnly Cookie Storage

Tokens are stored in HttpOnly, Secure, SameSite=Lax cookies. JavaScript cannot access them, eliminating XSS-based token theft. The refresh_token cookie is scoped to /api/auth/refresh to minimize exposure.

CSRF Double-Submit Cookie

A random CSRF token is set as a non-HttpOnly cookie and must be echoed in the X-CSRF-Token header on state-changing requests. The global CsrfGuard validates this for all cookie-authenticated POST/PUT/DELETE/PATCH requests.

Rate Limiting

All endpoints are protected by @nestjs/throttler with env-configurable limits (defaults: 100 requests per minute per IP globally, /api/auth/refresh at 5/min, /api/auth/login, /api/auth/callback, /api/auth/logout at 10/min, API key failed-attempt throttling at 20 failures/min/IP). All values can be overridden via environment variables — see auth.config.ts for the full list. Exceeding limits returns 429 Too Many Requests.

Security Headers (Helmet)

The helmet middleware sets HTTP security headers on all backend responses: Strict-Transport-Security (HSTS, 1 year), X-Frame-Options: DENY (clickjacking prevention), X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin, Content-Security-Policy, and removes X-Powered-By. The frontend nginx config also sets equivalent security headers.