Authorization Flows & Interaction Pages

How OIDC interactions are handled in the Next.js App Router, including the authorization code flow and consent lifecycle.

Supported Flows

Flow	Grant Type	Supported	Description
Authorization Code	`authorization_code`	Yes	Primary flow. User authenticates at `/login`, approves consent at `/consent`, receives an auth code at `/token`.
Refresh Token	`refresh_token`	Yes	Uses rotating refresh tokens (30-day expiry). Each refresh invalidates the previous token.
Client Credentials	`client_credentials`	Disabled	`clientCredentials.enabled` is `false`. Machine-to-machine access should use the authorization code flow with a service account instead.

Interaction Pages

During the OIDC authorization flow, oidc-provider redirects the browser to these App Router pages (served at root-level paths). They are NOT OIDC protocol endpoints — they are the UI forms that complete the interaction, communicating back via the _interaction cookie.

Path	Server Action	Description
`/login`	`completeLogin`	Login page. If the user already has a valid app session, the interaction auto-completes via `tryAutoLogin()`. Otherwise, the user enters credentials. Handles both OIDC interactions and regular app login.
`/register`	`completeRegister`	Registration page for new users. On success, assigns the `user` RBAC role and completes the OIDC login interaction (if active).
`/consent`	`approveConsent` / `denyConsent`	Consent page. Shows requested scopes and client name. If the client has a `required_role`, checks the user has it before rendering — redirects to `/unauthorized` if not.

Authorization Code Flow (Step-by-Step)

1. Client redirects user to /authorize with client credentials and requested scopes.
2. oidc-provider creates an interaction and sets the _interaction cookie, redirecting to /login.
3. User logs in (or auto-login completes). oidc-provider resolves the interaction and redirects to /consent.
4. User reviews requested scopes and clicks Approve. The Server Action approveConsent callsinteractionFinished().
5. oidc-provider generates an authorization code and redirects back to the client redirect URI.
6. Client exchanges the code at /token for access and refresh tokens.
7. Client uses the access token at /userinfo to retrieve the user identity.

Request Handling Architecture

oidc-provider expects Node.js req/res objects, but Next.js App Router uses Web Request. The bridge lives in src/lib/oauth2/handlers.ts:

ensureInitialized() — Runs once on cold start. Initializes JWKS keys (initJwksKeys()) and seeds RBAC defaults (seedRbac()).
handleOIDCRequest() — Creates mock Node.js IncomingMessage/ServerResponse from the Web Request, forwards to the oidc-provider callback handler, and converts the response back to NextResponse. Has a 15-second timeout.
DrizzleAdapter — In src/lib/oauth2/adapter.ts. Stores all OIDC sessions and tokens in the oauth_sessions table with composite keys ("Grant:uuid", etc.), expiration checks, and grant-based revocation.

Loading…

Supported Flows

Flow	Grant Type	Supported	Description
Authorization Code	`authorization_code`	Yes	Primary flow. User authenticates at `/login`, approves consent at `/consent`, receives an auth code at `/token`.
Refresh Token	`refresh_token`	Yes	Uses rotating refresh tokens (30-day expiry). Each refresh invalidates the previous token.
Client Credentials	`client_credentials`	Disabled	`clientCredentials.enabled` is `false`. Machine-to-machine access should use the authorization code flow with a service account instead.

Interaction Pages

Path	Server Action	Description
`/login`	`completeLogin`	Login page. If the user already has a valid app session, the interaction auto-completes via `tryAutoLogin()`. Otherwise, the user enters credentials. Handles both OIDC interactions and regular app login.
`/register`	`completeRegister`	Registration page for new users. On success, assigns the `user` RBAC role and completes the OIDC login interaction (if active).
`/consent`	`approveConsent` / `denyConsent`	Consent page. Shows requested scopes and client name. If the client has a `required_role`, checks the user has it before rendering — redirects to `/unauthorized` if not.

Authorization Code Flow (Step-by-Step)

1. Client redirects user to /authorize with client credentials and requested scopes.

2. oidc-provider creates an interaction and sets the _interaction cookie, redirecting to /login.

3. User logs in (or auto-login completes). oidc-provider resolves the interaction and redirects to /consent.

4. User reviews requested scopes and clicks Approve. The Server Action approveConsent callsinteractionFinished().

5. oidc-provider generates an authorization code and redirects back to the client redirect URI.

6. Client exchanges the code at /token for access and refresh tokens.

7. Client uses the access token at /userinfo to retrieve the user identity.

Request Handling Architecture

oidc-provider expects Node.js req/res objects, but Next.js App Router uses Web Request. The bridge lives in src/lib/oauth2/handlers.ts:

ensureInitialized() — Runs once on cold start. Initializes JWKS keys (initJwksKeys()) and seeds RBAC defaults (seedRbac()).

handleOIDCRequest() — Creates mock Node.js IncomingMessage/ServerResponse from the Web Request, forwards to the oidc-provider callback handler, and converts the response back to NextResponse. Has a 15-second timeout.

DrizzleAdapter — In src/lib/oauth2/adapter.ts. Stores all OIDC sessions and tokens in the oauth_sessions table with composite keys ("Grant:uuid", etc.), expiration checks, and grant-based revocation.