OAuth and OIDC Authentication Flow#

Overview#

Tinyauth handles OAuth and OIDC through two distinct entry points — forward auth (proxy mode) and OIDC server mode — each with a different user experience. The frontend passes context between pages using a small set of URL screen params (login_for, redirect_uri, oidc_ticket, oidc_scope, oidc_name, oidc_prompt) defined in screen-params.ts.

OAuth Auto-Redirect (Forward Auth Mode)#

When Tinyauth is used as a forward auth proxy and OAuth.AutoRedirect is set to a provider ID, the login page checks at mount time whether the named provider exists and a redirect_uri is present. If so, it skips the login UI and triggers an automatic OAuth redirect. 1

The auto-redirect fires exactly once (guarded by hasAutoRedirectedRef) by calling GET /api/oauth/url/:provider with the compiled screen params. 2 On success, the browser navigates to the provider after a 500 ms delay; if the redirect stalls beyond 5 seconds, a manual "redirect" button appears. 3 On error, auto-redirect mode is cancelled and the full login UI is shown. 4

The oauthURLHandler validates the redirect_uri against the app URL using isRedirectSafe() before creating a pending session — unsafe URIs are silently dropped. 5 isRedirectSafe requires matching scheme and port, and optionally permits subdomains of the configured cookie domain when SubdomainsEnabled is true.

OAuth Callback and Session Creation#

After the provider redirects back, oauthCallbackHandler verifies the PKCE state, exchanges the authorization code for tokens, fetches userinfo, enforces the email whitelist, and creates a session cookie.

The callback then branches on login_for:

• login_for=app (forward auth): redirects to /continue?redirect_uri=... to return the user to the originally requested URL. 6
• login_for=oidc (OIDC server): redirects to /oidc/authorize with the original OIDC params re-attached, resuming the two-stage OIDC flow. 7

Ticket-Based Two-Stage OIDC Authorization Flow#

When Tinyauth acts as an OIDC provider, the authorization flow is split into two stages to avoid exposing full OIDC request parameters in browser redirects.

Stage 1: /authorize — Ticket Creation#

GET/POST /authorize validates the OIDC request (client ID, redirect URI, prompt, PKCE), then creates a ticket — storing the full AuthorizeRequest in a 10-minute in-memory cache keyed by a random 32-character string. The handler then redirects to the frontend at /oidc/authorize?login_for=oidc&oidc_ticket=...&oidc_scope=...&oidc_name=...; the actual OIDC parameters are never in the redirect URL itself. 8

Prompt handling at this stage:

• prompt=none with no active session → immediate login_required error, no login redirect. 9
• prompt=login or expired max_age → ticket carries oidc_prompt=login, forcing re-authentication on the frontend. 10

Stage 2: Frontend Consent → /api/oidc/authorize-complete#

AuthorizePage reads the ticket and scope from URL params. If the user is unauthenticated or oidc_prompt=login, it redirects to /login with all screen params intact so the login page can complete authentication and return. 11 When oidc_prompt=none and the user is already authenticated, consent is automatically submitted without showing the UI. 12

On consent (explicit or automatic), the frontend POSTs the ticket to /api/oidc/authorize-complete. The backend retrieves and deletes the cached AuthorizeRequest, then issues an authorization code. The redirect URI with code and state is returned as JSON for the frontend to navigate to. 13

Token Exchange#

POST /api/oidc/token supports authorization_code and refresh_token grant types. Client credentials are accepted via form params or HTTP Basic auth. 14 Code reuse is actively detected: if a previously-issued code hash is re-submitted, the associated session is immediately revoked. 15

Forward Auth Entry Point (Proxy Controller)#

Unauthenticated requests reaching the proxy endpoint (/api/auth/:proxy) are redirected to /login?redirect_uri=...&login_for=app. 16 Browser detection uses a User-Agent regex (Chrome|Gecko|AppleWebKit|Opera|Edge); non-browser clients and Nginx always receive a 401 JSON response with an x-tinyauth-location header rather than a redirect. 17 18

On successful authentication, the proxy controller forwards Remote-User, Remote-Name, Remote-Email, Remote-Groups, and Remote-Sub headers to the upstream service. 19

Key Files#