Single Sign-On (SSO)

OIDC OAuth2 SSO

Single Sign-On (SSO) allows users to authenticate with multiple applications using a single set of credentials. This plugin supports OpenID Connect (OIDC) and OAuth2 providers.

Installation

import { betterAuth } from "better-auth"
import { sso } from "better-auth/plugins/sso";
 
const auth = betterAuth({
    plugins: [ 
        sso() 
    ] 
})

npx @better-auth/cli migrate

import { createAuthClient } from "better-auth/client"
import { ssoClient } from "better-auth/client/plugins"
 
const authClient = createAuthClient({
    plugins: [ 
        ssoClient() 
    ] 
})

Usage

Register an OIDC Provider

To register an OIDC provider, use the createOIDCProvider endpoint and provide the necessary configuration details for the provider.

A redirect URL will be 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. Note that /api/auth may vary depending on your base path configuration.

Example

import { authClient } from "@/lib/auth-client";
 
// only with issuer if the provider supports discovery
await authClient.sso.register({
    issuer: "https://idp.example.com",
    providerId: "example-provider",
});
 
// with all fields
await authClient.sso.register({
    issuer: "https://idp.example.com",
    domain: "example.com",
    clientId: "client-id",
    clientSecret: "client-secret",
    authorizationEndpoint: "https://idp.example.com/authorize",
    tokenEndpoint: "https://idp.example.com/token",
    jwksEndpoint: "https://idp.example.com/jwks",
    mapping: {
        id: "sub",
        email: "email",
        emailVerified: "email_verified",
        name: "name",
        image: "picture",
    },
    providerId: "example-provider",
});

Full method

const { data, error } = await authClient.sso.register({
    providerId: "example-provider", // required
    issuer: "https://idp.example.com", // required
    domain: "example.com", // required
    clientId: "1234567890", // required
    clientSecret: "1234567890", // required
    authorizationEndpoint: "https://idp.example.com/authorize",
    tokenEndpoint: "https://idp.example.com/token",
    userInfoEndpoint: "https://idp.example.com/userinfo",
    tokenEndpointAuthentication: "client_secret_post",
    jwksEndpoint: "https://idp.example.com/.well-known/jwks.json",
    discoveryEndpoint,
    scopes: ['openid', 'email', 'profile'],
    pkce: true,
    mapping: {
        id: "sub",
        email: "email",
        emailVerified: "email_verified",
        name: "name",
        image: "picture",
        extraFields,
    },
    organizationId: "some-org-id",
    overrideUserInfo,
});

Sign In with SSO

To sign in with an SSO provider, you can call signIn.sso

You can sign in using the email with domain matching:

const res = await authClient.signIn.sso({
    email: "user@example.com",
    callbackURL: "/dashboard",
});

or you can specify the domain:

const res = await authClient.signIn.sso({
    domain: "example.com",
    callbackURL: "/dashboard",
});

You can also sign in using the organization slug if a provider is associated with an organization:

const res = await authClient.signIn.sso({
    organizationSlug: "example-org",
    callbackURL: "/dashboard",
});

Alternatively, you can sign in using the provider's ID:

const res = await authClient.signIn.sso({
    providerId: "example-provider-id",
    callbackURL: "/dashboard",
});

To use the server API you can use signInSSO

const res = await auth.api.signInSSO({
    body: {
        organizationSlug: "example-org",
        callbackURL: "/dashboard",
    }
});

Full method

const { data, error } = await authClient.signIn.sso({
    email: "john@example.com",
    organizationSlug: "example-org",
    providerId: "example-provider",
    domain: "example.com",
    callbackURL: "https://example.com/callback", // required
    errorCallbackURL: "https://example.com/callback",
    newUserCallbackURL: "https://example.com/new-user",
    scopes: ["openid", "email", "profile", "offline_access"],
    requestSignUp: true,
});

When a user is authenticated, if the user does not exist, the user will be provisioned using the provisionUser function. If the organization provisioning is enabled and a provider is associated with an organization, the user will be added to the organization.

const auth = betterAuth({
    plugins: [
        sso({
            provisionUser: async (user) => {
                // provision user
            },
            organizationProvisioning: {
                disabled: false,
                defaultRole: "member",
                getRole: async (user) => {
                    // get role if needed
                },
            },
        }),
    ],
});

Schema

The plugin requires additional fields in the ssoProvider table to store the provider's configuration.

Options

Server

provisionUser: A custom function to provision a user when they sign in with an SSO provider.

organizationProvisioning: Options for provisioning users to an organization.