Search documentation

Search documentation pages and headings.

Skip to content

Integration · How-to guide

OAuth and OIDC

Integrate through authorization code flow, PKCE, standard discovery, scopes, and secure token handling.

Krakstack Auth publishes OpenID Connect and OAuth authorization-server metadata and supports authorization code flow. Use a maintained OAuth/OIDC library in the consumer rather than assembling authorization requests and token validation manually.

Register a client#

In Admin > Clients, create a client and configure:

  • A recognizable display name
  • Exact redirect URIs, including scheme, hostname, path, and port
  • The minimum scopes required: openid, profile, email, and optionally offline_access
  • An optional linked project for branding and enabled authentication options

Copy the client ID and secret immediately. The secret is shown once and belongs only in server-side secret storage. Current admin-created clients are confidential Web clients using client_secret_basic; they also require PKCE. Public and native client registration is not currently exposed.

Discovery#

Read the actual metadata before configuring a client:

text
Root OIDC metadata: https://auth.example.com/.well-known/openid-configurationOAuth metadata: https://auth.example.com/.well-known/oauth-authorization-server/api/auth

Use the exact issuer, authorization endpoint, token endpoint, and JWKS URI returned by the service. Better Auth's effective issuer can include /api/auth; do not configure the bare origin unless the metadata reports it.

Authorization flow#

  1. Generate a cryptographically random state, nonce, and PKCE verifier.
  2. Store them in a short-lived, secure, HttpOnly session.
  3. Redirect to the discovered authorization endpoint with response_type=code.
  4. On callback, compare state before exchanging the code.
  5. Exchange the code server-side and validate issuer, audience, signature, nonce, and expiry.
  6. Create or rotate the application's own session.

Redirect URI rules#

Production redirect URIs should use HTTPS and exact matching. Do not use wildcard callback hosts. Register localhost callbacks separately for development and remove unused callbacks as deployments change.

Tokens#

Keep access and refresh tokens out of local storage. Prefer server-side encrypted session storage or secure HttpOnly cookies. Request offline_access only when background access is required, rotate refresh tokens, and revoke credentials when users disconnect the application.