Single Sign-On (SSO)
OIDC
OAuth2
SSO
SAML
Single Sign-On (SSO) allows users to authenticate with multiple applications using a single set of credentials. This plugin supports OpenID Connect (OIDC), OAuth2 providers, and SAML 2.0.
Installation
Add Plugin to the server
Migrate the database
Run the migration or generate the schema to add the necessary fields and tables to the database.
See the Schema section to add the fields manually.
Add the client plugin
Usage
Register an OIDC Provider
To register an OIDC provider, use the registerSSOProvider
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
Register a SAML Provider
To register a SAML provider, use the registerSSOProvider
endpoint with SAML configuration details. The provider will act as a Service Provider (SP) and integrate with your Identity Provider (IdP).
Get Service Provider Metadata
For SAML providers, you can retrieve the Service Provider metadata XML that needs to be configured in your Identity 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:
or you can specify the domain:
You can also sign in using the organization slug if a provider is associated with an organization:
Alternatively, you can sign in using the provider's ID:
To use the server API you can use signInSSO
Full method
Prop | Description | Type |
---|---|---|
email? | The email address to sign in with. This is used to identify the issuer to sign in with. It's optional if the issuer is provided. | string |
organizationSlug? | The slug of the organization to sign in with. | string |
providerId? | The ID of the provider to sign in with. This can be provided instead of email or issuer. | string |
domain? | The domain of the provider. | string |
callbackURL | The URL to redirect to after login. | string |
errorCallbackURL? | The URL to redirect to after login. | string |
newUserCallbackURL? | The URL to redirect to after login if the user is new. | string |
scopes? | Scopes to request from the provider. | string[] |
requestSignUp? | Explicitly request sign-up. Useful when disableImplicitSignUp is true for this provider. | boolean |
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.
Provisioning
The SSO plugin provides powerful provisioning capabilities to automatically set up users and manage their organization memberships when they sign in through SSO providers.
User Provisioning
User provisioning allows you to run custom logic whenever a user signs in through an SSO provider. This is useful for:
- Setting up user profiles with additional data from the SSO provider
- Synchronizing user attributes with external systems
- Creating user-specific resources
- Logging SSO sign-ins
- Updating user information from the SSO provider
The provisionUser
function receives:
- user: The user object from the database
- userInfo: User information from the SSO provider (includes attributes, email, name, etc.)
- token: OAuth2 tokens (for OIDC providers) - may be undefined for SAML
- provider: The SSO provider configuration
Organization Provisioning
Organization provisioning automatically manages user memberships in organizations when SSO providers are linked to specific organizations. This is particularly useful for:
- Enterprise SSO where each company/domain maps to an organization
- Automatic role assignment based on SSO attributes
- Managing team memberships through SSO
Basic Organization Provisioning
Advanced Organization Provisioning with Custom Roles
Linking SSO Providers to Organizations
When registering an SSO provider, you can link it to a specific organization:
Now when users from acmecorp.com
sign in through this provider, they'll automatically be added to the "Acme Corp" organization with the appropriate role.
Multiple Organizations Example
You can set up multiple SSO providers for different organizations:
Organization Provisioning Flow
- User signs in through an SSO provider linked to an organization
- User is authenticated and either found or created in the database
- Organization membership is checked - if the user isn't already a member of the linked organization
- Role is determined using either the
defaultRole
orgetRole
function - User is added to the organization with the determined role
- User provisioning runs (if configured) for additional setup
Provisioning Best Practices
1. Idempotent Operations
Make sure your provisioning functions can be safely run multiple times:
2. Error Handling
Handle errors gracefully to avoid blocking user sign-in:
3. Conditional Provisioning
Only run certain provisioning steps when needed:
SAML Configuration
Service Provider Configuration
When registering a SAML provider, you need to provide Service Provider (SP) metadata configuration:
- metadata: XML metadata for the Service Provider
- binding: The binding method, typically "post" or "redirect"
- privateKey: Private key for signing (optional)
- privateKeyPass: Password for the private key (if encrypted)
- isAssertionEncrypted: Whether assertions should be encrypted
- encPrivateKey: Private key for decryption (if encryption is enabled)
- encPrivateKeyPass: Password for the encryption private key
Identity Provider Configuration
You also need to provide Identity Provider (IdP) configuration:
- metadata: XML metadata from your Identity Provider
- privateKey: Private key for the IdP communication (optional)
- privateKeyPass: Password for the IdP private key (if encrypted)
- isAssertionEncrypted: Whether assertions from IdP are encrypted
- encPrivateKey: Private key for IdP assertion decryption
- encPrivateKeyPass: Password for the IdP decryption key
SAML Attribute Mapping
Configure how SAML attributes map to user fields:
SAML Endpoints
The plugin automatically creates the following SAML endpoints:
- SP Metadata:
/api/auth/sso/saml2/sp/metadata?providerId={providerId}
- SAML Callback:
/api/auth/sso/saml2/callback/{providerId}
Schema
The plugin requires additional fields in the ssoProvider
table to store the provider's configuration.
Field Name | Type | Key | Description |
---|---|---|---|
id | string | A database identifier | |
issuer | string | - | The issuer identifier |
domain | string | - | The domain of the provider |
oidcConfig | string | - | The OIDC configuration (JSON string) |
samlConfig | string | - | The SAML configuration (JSON string) |
userId | string | - | The user ID |
providerId | string | - | The provider ID. Used to identify a provider and to generate a redirect URL. |
organizationId | string | - | The organization Id. If provider is linked to an organization. |
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.
defaultOverrideUserInfo: Override user info with the provider info by default.
disableImplicitSignUp: Disable implicit sign up for new users.
trustEmailVerified: Trust the email verified flag from the provider.
Prop | Type | Default |
---|---|---|
provisionUser? | function | - |
organizationProvisioning? | object | - |
defaultOverrideUserInfo? | boolean | - |
disableImplicitSignUp? | boolean | - |
providersLimit? | number | function | 10 |