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/hydra. Note that /api/auth may vary depending on your base path configuration.

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",
});

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: "[email protected]",
    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",
    }
});

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.