Auth Flow

The authentication flow is the process of checking that a user is authorised to access a specific piece of data. For this reason, it is a server-side process. Technical terminology will be used, with explanations in the footnotes. This is each step in detail:

API Server Startup

Startup Flow Diagram

Pre-flight validation:
- Ensures that OIDC_ISSUER from the environment exists.
- If it doesn’t, the server logs an error and exits with process.exit(1).
OIDC discovery:
1. The server queries the OIDC provider’s standard discovery endpoint:
  - /.well-known/openid-configuration
2. It reads the jwks_uri from the response.
3. If discovery fails, it falls back to Authelia’s default JWKS path:
  - ${ISSUER}/jwks.json
JWKS setup:
- The resolved JWKS URI is passed to jose’s createRemoteJWKSet.
- jose handles key fetching and caching automatically, including rotation.
Runtime server setup:
- The server also prepares:
  - a default Content Security Policy
  - lightweight in-memory API rate limiting
  - request logging
  - cached reads for data/config.json and data/protected-apps.json
Listen:
- The server begins accepting connections.

Per Request (e.g. `protected-apps.json`)

Auth Flow Diagram

A request arrives for a protected endpoint such as:
- /api/protected-apps.json
- /api/me
The server applies security headers on every response:
- Content-Security-Policy
- Cross-Origin-Opener-Policy: same-origin
- Cross-Origin-Resource-Policy: same-origin
- Origin-Agent-Cluster: ?1
- X-Content-Type-Options: nosniff
- X-DNS-Prefetch-Control: off
- X-Frame-Options: DENY
- Referrer-Policy: strict-origin-when-cross-origin
- Permissions-Policy: camera=(), microphone=(), geolocation=()
If configured, the server may also apply:
- Strict-Transport-Security
- CORS headers via CORS_ORIGIN
If the route begins with /api/, the server checks a lightweight per-IP rate limit window.
- If the limit is exceeded, it responds with:
  - 429 Too Many Requests
Route matching occurs.
- In this case, /api/protected-apps.json or /api/protected-apps.
auth.authenticate(req) is called:
1. Extract the JWT:
  - Reads the Authorization header.
  - Expects Bearer <token>.
  - If missing or malformed, returns null.
2. Verify the JWT:
  - Passes the token, the JWKS, and issuer/audience expectations into jose’s jwtVerify.
  - jose:
    1. Finds the correct public key from the token’s kid
    2. Verifies the signature
    3. Validates iss
    4. Validates aud
    5. Validates expiry
  - Any failure returns null.
3. Build the user object:
  - sub: from sub
  - name: from name, then preferred_username, then "User"
  - email: from email, else null
  - groups: from groups if it is an array, else []
  - claims: the raw verified payload
4. Return the user object.
loadItems() is called:
1. Reads data/protected-apps.json
2. Parses it as JSON
3. Validates:
  - root is an array
  - each item is an object
  - each item has a valid id
  - each item has a valid label
  - each item has either subdomain or url
  - duplicates are dropped by id
4. Invalid entries are logged and ignored
5. Valid entries are cached until the file changes
The protected items are filtered by group:
- If requiredGroup is not present, the item is visible to any authenticated user
- If requiredGroup is present, the user must belong to that group
Response headers are set:
- Cache-Control: no-store
- Vary: Authorization
  or Vary: Authorization, Origin when CORS is enabled
JSON is returned.

Login Flow

The login flow is the process of proving your identity. This is primarily handled by the OIDC provider, but some of it is handled by the frontend. This is each step in detail:

User is not authenticated and initiates login.
Generate a PKCE pair:
- verifier: random bytes, base64url encoded
- challenge: SHA-256 hash of the verifier, base64url encoded
Generate state and nonce:
- Both are random values used for CSRF and replay protection
Store PKCE redirect-only values in sessionStorage:
- pkce_verifier
- oidc_state
- oidc_nonce
These values only need to survive the redirect round-trip.
Store the user’s current in-app path so the app can return them to it after login completes.
Redirect to the OIDC provider’s authorization endpoint with:
- response_type=code
- client_id
- redirect_uri
- scope
- state
- nonce
- code_challenge
- code_challenge_method=S256
Scope details:
- The default requested scope is:
  - openid profile email groups offline_access
- groups is needed for group-based visibility
- offline_access enables refresh tokens, which allows persistent sessions
The user authenticates with the provider.
The provider redirects back to the configured redirect_uri with:
- code
- state
checkAuth() runs on the client:
Detects code and state in the URL
Calls handleCallback(code, state)
handleCallback():
Reads savedState, savedVerifier, and savedNonce from sessionStorage
Removes them from sessionStorage
Verifies:
- returned state matches savedState
- savedVerifier exists
POSTs to the token endpoint with:
- grant_type=authorization_code
- client_id
- code
- redirect_uri
- code_verifier
If the exchange succeeds, the provider returns:

id_token
access_token
optionally refresh_token

The client validates the id_token claims locally:

nonce must match savedNonce
exp must be in the future, with a small clock-skew tolerance
aud must match the expected client ID
iss must match the expected issuer when present

Tokens are stored as follows:

sessionStorage:
- only PKCE state/verifier/nonce
localStorage:
- id_token
- refresh_token when provided

This means:

redirect-only verification state is temporary
login session can persist across reloads and browser restarts

applyTokenClaims(claims) runs:

user.displayName = claims.name || claims.preferred_username || 'User'
user.emails = claims.email ? [claims.email] : []
groups = Array.isArray(claims.groups) ? claims.groups : []

Query params are cleaned from the URL:

code
state
iss
scope

The SPA navigates back to the originally requested in-app route, if one was saved before login started.

Fetching Protected Dashboard Items

Now that you understand both the client and server authentication flows, I can explain how protected items on the dashboard are fetched and displayed.

User visits the site.
checkAuth() runs.
If the user is authenticated, fetchProtectedApps() is called.
The client reads id_token from localStorage.
If no id_token exists:
- protectedItems becomes []
- no protected data is shown
A GET request is sent to protectedAppsUrl with:
- Authorization: Bearer <id_token>
- Accept: application/json
The server validates the token and filters the items by group.
The client receives the filtered array.
The client then applies a second, defensive filter:
- if requiredGroup is absent, keep the item
- otherwise, only keep the item if the user’s groups include it
protectedItems is updated.
The dashboard combines:

public items from config
protected items from the API

The combined list is deduplicated by id before rendering.

Returning Visit

When an authenticated user returns to the site:

User visits the website.
checkAuth() runs.
No code parameter exists in the URL, so callback handling is skipped.
restoreSession() runs:
1. Reads id_token from localStorage
2. If id_token exists:
  1. decodes it
  2. validates exp, aud, and iss
  3. restores user/group state
  4. Reconciles the restored session againt the server by calling GET /api/me:
    - If the server accepts it, session is treated as fully restored.
    - If the server rejects it, falls through to step 4.3.
3. If id_token is missing or invalid:
  - removes it from localStorage
  - falls through to refresh token flow

Refresh Flow

This flow is invoked when the user has an invalid or missing id_token, but still has a usable refresh_token.

Read refresh_token from localStorage.
If missing:
- refresh flow ends
- user remains unauthenticated
POST to the token endpoint with:
- grant_type=refresh_token
- client_id
- refresh_token
If the provider accepts it, it may return:
- a fresh id_token
- optionally a rotated refresh_token
If the response is not OK:
- refresh_token is removed from localStorage
- refresh fails cleanly
If id_token is missing from the response:
- the refresh attempt is treated as failed
If id_token exists:
- decode and validate claims
- save the new id_token
- replace refresh_token if a rotated one is provided
- re-apply user claims
If any error occurs during refresh:
- the stored refresh_token is removed
- the user is effectively logged out

Why This Storage Model?

A subtle but important detail:

sessionStorage is used only for:
- PKCE verifier
- OIDC state
- nonce
localStorage is used for:
- id_token
- refresh_token

This is deliberate.

The redirect-protection values should be short-lived and tab-scoped.
The tokens are stored more persistently so the user doesn’t need to log in every time they reopen the site.

That persistence comes with a tradeoff:

localStorage is readable by JavaScript
so XSS protection matters a lot

For that reason, the app also relies on:

CSP
minimal third-party script usage
server-side JWT verification
narrow token usage
limited sensitivity of the protected data itself

Summary

The auth system is split cleanly into two roles:

Client

Performs OIDC Authorization Code + PKCE
Stores redirect-only verification data in sessionStorage
Stores tokens in localStorage
Restores sessions
Refreshes tokens
Sends bearer tokens to the API
Applies a client-side defense-in-depth filter

Server

Discovers and caches JWKS
Validates JWT signatures and claims
Applies security headers
Rate limits API access
Validates runtime config and protected item files
Filters protected items by group
Returns only what the user should see

That gives me a setup that is:

portable
proxy-agnostic
per-user aware
easy to self-host
and strong enough for this kind of application without needing reverse-proxy forward-auth glue.