new·Earn with mozg — 20% of every monthSend somebody here and take a fifth of every plan payment they make, for as long as they keep paying — not a bounty on the first invoice. Your handle is the link, the window is thirty days, and the commission lands on your balance the second they pay. Free to join: if you have signed in, you already have the link. mozg.sh/earnall news →
mozg.beta
Sign in

Better Auth · Plugins · all subjects

sso/oidc

10 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

OIDC provider registration with automatic discovery

Register an OIDC provider using the `registerSSOProvider` endpoint. Required fields: providerId (unique identifier, must not collide with social providers or reserved IDs), issuer (OIDC issuer URL), domain (bare email domain or comma-separated domains), and oidcConfig containing clientId and clientSecret. Most OIDC endpoint fields are optional and auto-discovered from the issuer's discovery document at `{issuer}/.well-known/openid-configuration`. Fields automatically discovered include: authorizationEndpoint, tokenEndpoint, jwksEndpoint, userInfoEndpoint, discoveryEndpoint, and tokenEndpointAuthentication.

OIDC callback URL generation

A redirect URL is automatically generated using the provider ID. For instance, if the provider ID is 'hydra', the redirect URL would be `{baseURL}/api/auth/sso/callback/hydra`. The `/api/auth` portion may vary depending on base path configuration.

OIDC account identification

Better Auth identifies an OIDC account by the provider ID and the verified `sub` claim from the ID token. The `mapping` option maps profile fields such as email, name, and image, but it cannot replace the account subject (sub claim).

OIDC discovery endpoint validation and relative URLs

Better Auth fetches the OIDC discovery document from `{issuer}/.well-known/openid-configuration` and validates it. Relative endpoint paths are supported and resolved relative to the issuer's base URL, preserving the path when available. Example: issuer `https://your-org.okta.com` with `token_endpoint: /v1/tokens` normalizes to `https://your-org.okta.com/v1/tokens`. Example: issuer `https://your-org.okta.com/v1` with `token_endpoint: /tokens` normalizes to `https://your-org.okta.com/v1/tokens`.

OIDC discovery does not follow redirects

Better Auth does not follow redirects for server-side OIDC requests. Configure the final canonical URL for discovery, token, userinfo, and JWKS endpoints. If any of these endpoints returns a 3xx response, registration or sign-in fails with `oidc_endpoint_redirect` error code.

OIDC implicit-only flows not supported

Better Auth does not support implicit-only OIDC flows. For this reason, `token_endpoint` and `jwks_uri` are required even though the OIDC spec allows implicit-only providers to omit `token_endpoint`.

OIDC discovery error codes

OIDC discovery can fail with these structured error codes: `issuer_mismatch` (IdP discovery document reports different issuer), `discovery_incomplete` (required fields missing: authorization_endpoint, token_endpoint, jwks_uri), `discovery_not_found` (discovery document returned 404), `discovery_timeout` (IdP did not respond within timeout, default 10 seconds), `discovery_invalid_url` (malformed URL or unsupported protocol), `discovery_untrusted_origin` (discovery URL or discovered URLs not trusted by app's trustedOrigins), `discovery_invalid_json` (response is empty or not valid JSON), `oidc_endpoint_redirect` (discovery, token, userinfo, or JWKS endpoint returned redirect), `unsupported_token_auth_method` (IdP only supports unsupported token auth methods).

OIDC token endpoint authentication methods

Supported token endpoint authentication methods for OIDC are `client_secret_basic` and `client_secret_post`. If the IdP advertises only unsupported methods (e.g., `private_key_jwt`, `tls_client_auth`, or `none`), you can explicitly override the method by setting `tokenEndpointAuthentication` in oidcConfig.

OIDC trustedOrigins configuration for discovery

Both the discovery endpoint and any URL resolved through the discovery process are subject to the app's `trustedOrigins` configuration. Discovery will fail with `discovery_untrusted_origin` code unless you explicitly update your `trustedOrigins` configuration. You can specify a list of well-known IDPs ahead of time or use a callback function that dynamically computes `trustedOrigins` based on the request.

SAML IdP-initiated SSO configuration

For OIDC providers that initiate logins without sending a `state` parameter, set `allowIdpInitiated: true` on the provider's oidcConfig. When a stateless callback arrives, the IdP-issued code is discarded and a new OAuth flow is started server-side with fresh state and PKCE verifier. CSRF protection remains in effect. This flag defaults to false. The global `baseURL` option must be set when enabling allowIdpInitiated; if unset, the bounce fails with `CALLBACK_URL_REQUIRED`.

Give your agent this brain