sso plugin

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

SSO schema additionalFields configuration

You can add custom columns to the ssoProvider table using schema.ssoProvider.additionalFields. For example, displayName can be added as a custom field with type 'string' and required: true, which can then be included when registering or updating a provider.

SSO provider domain verification token expiry

Every domain verification token has a default expiry of 1 week from the moment it was issued or when the SSO provider was registered. After that time, the token expires and cannot be used.

POST /sso/verify-domain endpoint

POST /sso/verify-domain endpoint requires session and accepts a request with providerId (string, example: "acme-corp"). Verification applies to the provider's exact domain configuration when the request starts. If the provider is updated or deleted while verification is in progress, the request returns a 409 response with SSO_PROVIDER_CHANGED code.

POST /sso/request-domain-verification endpoint

POST /sso/request-domain-verification endpoint requires session and accepts a request with providerId (string, example: "acme-corp"). This endpoint creates a new domain verification token when a previous token has expired.

SAML SP Metadata endpoint

The SSO plugin automatically creates the SAML SP Metadata endpoint at /api/auth/sso/saml2/sp/metadata?providerId={providerId}

SAML ACS endpoint

The SSO plugin automatically creates the SAML Assertion Consumer Service (ACS) endpoint at /api/auth/sso/saml2/sp/acs/{providerId}, which supports both GET and POST methods.

SAML callback URL configuration with callbackURL parameter

The post-login redirect destination is controlled by the callbackURL parameter in the client-side signIn.sso() call. For example: await authClient.signIn.sso({ providerId: "my-provider", callbackURL: "/dashboard" });

IdP-initiated SAML callback URL configuration

For unsolicited IdP-initiated flows where signIn.sso() is not used (no client-side callbackURL), configure idpInitiatedCallbackUrl in the provider's samlConfig or in the global saml plugin options. The provider setting takes precedence over the global setting. When updating a provider, pass null for samlConfig.idpInitiatedCallbackUrl to remove its override and fall back to the global setting.

SAML ACS endpoint automatic GET/POST handling

The callback route (/api/auth/sso/saml2/sp/acs/{providerId}) supports both GET and POST methods automatically, so no additional route handlers need to be created in the framework.

SAML AudienceRestriction validation

Your Identity Provider must include an AudienceRestriction for the SP. The accepted audience is the SP entity ID, or the explicit audience value in samlConfig when needing to match an IdP-specific SP identifier. Better Auth also checks bearer Recipient and response Destination values against the provider's ACS endpoints.

SSO provider schema - ssoProvider table fields

The ssoProvider table has the following fields: id (string, primary key), issuer (string), domain (string), oidcConfig (string, optional, JSON string), samlConfig (string, optional, JSON string), userId (string, foreign key to user.id), providerId (string, unique), organizationId (string, optional). When domain verification is enabled, an additional domainVerified (boolean, optional) field is added.

SSO additionalFields example configuration

Example configuration for adding a displayName field to ssoProvider: sso({ schema: { ssoProvider: { additionalFields: { displayName: { type: "string", required: true } } } } }). Then include the field when registering: await auth.api.registerSSOProvider({ body: { providerId: "okta-main", displayName: "Okta", issuer: "https://idp.example.com", domain: "example.com", oidcConfig: { clientId: "client-id", clientSecret: "client-secret" } }, headers });

IdP-initiated SAML SSO flow description

IdP-initiated SSO is where users access the application directly from their Identity Provider dashboard (e.g., Okta, Azure AD, OneLogin). The flow: user clicks app icon in IdP dashboard, IdP POSTs SAMLResponse to /api/auth/sso/saml2/sp/acs/{providerId}, Better Auth processes the assertion and creates a session, then redirects to the application with a GET request (handled automatically).

IdP-initiated SAML SSO callback configuration pitfall

IdP-initiated flows do not carry a Better Auth-generated RelayState containing a client-side callback URL. In split-origin setups where the app frontend is on a different origin than the Better Auth server, the redirect falls back to the Better Auth base URL, which lands on the auth server origin and can result in a 404. Configure idpInitiatedCallbackUrl globally under saml plugin options or per provider under samlConfig to return successful sign-ins to the frontend.

SAML redirect URL security validation

Better Auth validates all redirect URLs to prevent open redirect attacks. Only relative paths (e.g., /dashboard) and URLs matching configured trustedOrigins are allowed. Malicious URLs like https://evil.com or protocol-relative URLs (//evil.com) are automatically blocked.

SSO plugin provisionUser option

The provisionUser option is a custom function to provision a user when they sign in with an SSO provider.

SSO plugin provisionUserOnEveryLogin option

The provisionUserOnEveryLogin option (boolean, default: false) controls whether the provisionUser callback runs on every login, not just when a new user is registered.

SSO plugin organizationProvisioning option

The organizationProvisioning option (object) has properties: disabled (boolean, default: false) to disable organization provisioning, defaultRole (string enum: 'member' or 'admin', default: 'member') for the default role for new users, and getRole (function) for custom role determination.

SSO plugin defaultOverrideUserInfo option

The defaultOverrideUserInfo option (boolean, default: false) controls whether to override user info with the provider info by default.

SSO plugin disableImplicitSignUp option

The disableImplicitSignUp option (boolean, default: false) disables implicit sign up for new users. When set to true, sign-in needs to be called with requestSignUp as true to create new users.

SSO plugin providersLimit option

The providersLimit option (number or function, default: 10) configures the maximum number of SSO providers a user can register. Set to 0 to disable SSO provider registration.

SSO plugin redirectURI option

The redirectURI option (string, optional) allows custom redirect URI for OIDC SSO callbacks. When set, all OIDC providers share this single callback URL instead of per-provider URLs, and the provider ID is stored in the OAuth state. Can be a relative path (e.g., '/sso/callback') or a full URL.

SSO plugin domainVerification option

The domainVerification option (object) has properties: enabled (boolean, optional) to enable or disable the domain verification feature, and tokenPrefix (string, optional, default: 'better-auth-token') for the prefix used to generate the domain verification identifier. An underscore is automatically prepended to the tokenPrefix.

SSO plugin defaultSSO option

The defaultSSO option (array) configures default SSO providers for testing and development. These providers will be used when no matching provider is found in the database. Each item has properties: domain (string, required, bare email domain or comma-separated domains), providerId (string, required), samlConfig (optional SAMLConfig), oidcConfig (optional OIDCConfig).

SSO plugin saml security options

The saml option (object) contains SAML security options: enableInResponseToValidation (boolean, default: true) for SP-initiated SAML flows, allowIdpInitiated (boolean, default: true) to allow IdP-initiated SSO, requestTTL (number, default: 300000ms) for AuthnRequest record TTL, clockSkew (number, default: 300000ms) for timestamp validation tolerance, requireTimestamps (boolean, default: false) to require timestamp conditions, algorithms.onDeprecated (string enum: 'reject', 'warn', 'allow', default: 'warn') for deprecated algorithm behavior, maxResponseSize (number, default: 262144 bytes), maxMetadataSize (number, default: 102400 bytes).

SSO plugin modelName option

The modelName option (string, default: 'ssoProvider') specifies the model name for the SSO provider table.

SSO plugin fields option for custom column names

The fields option allows customizing column names in the ssoProvider table: issuer (default: 'issuer'), oidcConfig (default: 'oidcConfig'), samlConfig (default: 'samlConfig'), userId (default: 'userId'), providerId (default: 'providerId'), organizationId (default: 'organizationId'), domain (default: 'domain').

Give your agent this brain