Browser applications

Use Authorization Code with PKCE. Choose the token owner before implementing login.

For a BFF, the browser follows redirects while the application server owns code exchange, token refresh and the application session. openid-client and oauth4webapi are suitable server libraries.

For a public SPA, @openid/appauth and oidc-client-ts provide the equivalent browser protocol client. Identity discovery is cross-origin readable, but token, revocation and UserInfo requests do not currently authorize arbitrary cross-origin application origins. Use the browser-only SPA tutorial to check that constraint before implementation.

Required invariants

• Register every callback exactly. Wildcards are not a substitute for per-environment registration.
• Generate state, nonce and the PKCE verifier in the token-owning client and bind them to one short-lived login attempt.
• Validate callback state, issuer and redirect target in that same client before code exchange.
• For a BFF, keep OAuth access and refresh tokens out of browser JavaScript and browser storage.
• For a public SPA, register tokenEndpointAuthMethod: NONE, ship no secret and treat script execution as part of the token security boundary.
• Serialize refresh for one session and persist rotating refresh tokens atomically in the token owner’s protected storage.
• Use the discovery document from the configured issuer and verify its exact issuer value.

Authorization request

GET {authorization_endpoint}
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fapi%2Fauth%2Fcallback
  &scope=openid%20email
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

The authorization server may require account selection, login, MFA or consent. The client resumes only from its registered callback.

Continue with web login through a BFF or browser-only SPA login.

Reauthentication

When a sensitive product action needs fresh authentication, start a new authorization request using the client policy and OIDC parameters required by that action. Do not infer freshness from the age of an application cookie.