Skip to main content
Docs

Organization-level Enterprise SSO

Clerk provides Enterprise Single Sign-On (SSO) through a feature called Enterprise Connections. You can enable Enterprise Connections for specific Organizations, allowing members to authenticate through their company's identity provider using SAML or OIDC protocols.

When users sign up or sign in using an Organization's Enterprise Connection, Clerk automatically adds them as members of that Organization and assigns them the default Role. This process is known as Just-in-Time (JIT) provisioning.

When to use Enterprise SSO

Enterprise SSO works well when customers require centralized authentication through their Identity Provider (IdP). This approach fits scenarios where:

  • Enterprise customers have security requirements that mandate IdP-based authentication.
  • IT teams need to manage user provisioning from a central location.
  • Organizations want to maintain existing identity management workflows.

If you need manual control over who joins and their Roles, use invitations. If you want automatic enrollment without IdP requirements, use Verified Domains.

Common onboarding flows

The timing of when you set up Enterprise SSO depends on how customers adopt your product. The two common approaches are to create the Organization and configure SSO before users sign in (top-down) or to let users start individually and add SSO later (bottom-up).

Organization created first (top-down approach)

This flow is common for enterprise sales where the relationship is established before users access the application.

  1. Create an Organization for your customer through the Clerk Dashboard.
  2. Collaborate with the customer's IT administrator to obtain the necessary configuration details.
  3. Configure the Enterprise SSO Connection for the Organization.
  4. Invite users to the Organization, who can then sign in using Enterprise SSO.

User-initiated setup (bottom-up approach)

This flow is common when individual users try the product before company-wide adoption.

  1. An end user signs up to evaluate your application, starting with an individual account.
  2. After adopting the application, the user creates an Organization for their company.
  3. Configure Enterprise SSO for the Organization through the Clerk Dashboard.
  4. All subsequent users from that Organization can now sign in using Enterprise SSO.

Add an Enterprise SSO connection for an Organization

Clerk supports Enterprise SSO via SAML or via the OpenID Connect (OIDC) protocol, either through EASIE or by integrating with any OIDC-compatible provider.

To add an Enterprise SSO Connection for an Organization, go to the Enterprise Connections docs and follow the appropriate guide based on the platform you want to use, such as the Google SAML guide. When configuring the connection in the Clerk Dashboard, there will be an option to select the Organization for which you want to enable this connection. If you don't select an Organization, Clerk will add the connection for your entire application.

Warning

A domain used for Enterprise SSO can't be used as a Verified Domain for the same Organization.

Enforce Enterprise SSO by domain

Clerk enforces Enterprise SSO connections on a per-domain basis in Organizations, enabling flexible access management:

  • Configure Enterprise SSO for your primary domain (e.g., company.com) to enforce Enterprise SSO authentication for employees.
  • Add additional domains without Enterprise SSO for external collaborators (e.g., contractors, consultants).
  • Each domain in an Organization can have different authentication requirements.

Remove a member from your Organization

Users who joined through an Enterprise Connection cannot leave the Organization on their own. You can remove them through the Clerk Dashboard, the Backend API, or by another member with the manage members Permission (org:sys_memberships:manage). However, the user will be added back to the Organization on next sign-in, unless they are removed from the IdP or the Enterprise Connection is no longer associated with the Organization.

Removed users will automatically rejoin the Organization on their next sign-in unless you also remove them from the IdP or disconnect the Enterprise Connection.

Move an Enterprise Connection to a different Organization

When you reassign an Enterprise Connection to a new Organization, existing members stay in the original Organization. They will automatically join the new Organization the next time they sign in.

Common SSO setup errors

When setting up Enterprise SSO, you may encounter errors during the authentication flow. The type of error you see depends on which protocol your Enterprise Connection uses:

  • SAML errors occur when using SAML-based Enterprise Connections (e.g., Azure AD, Google Workspace, Okta). These errors typically relate to SAML assertion validation, attribute mapping, or domain configuration issues.
  • OAuth errors occur when using OAuth/OIDC-based Enterprise Connections (e.g., custom OIDC providers, EASIE). These errors typically relate to authorization flows, token exchange, or user information retrieval.

The following sections describe common error codes and how to resolve them.

saml_user_attribute_missing

You will encounter this error when the user's account is missing a required attribute, for example, a mail attribute.

How to fix it:

Access your identity provider's configuration dashboard, navigate to your application's SAML settings or attribute mapping configuration, and ensure that the 'mail' attribute is properly mapped to the user's email address field.

saml_response_relaystate_missing

You will encounter this error when the RelayState parameter is missing from the SAML Response.

How to fix it:

Check that your identity provider is correctly returning the RelayState parameter that was sent in the original request.

saml_email_address_domain_mismatch

You will encounter this error when the email address domain of the user's account does not match the domain configured for the connection.

How to fix it:

  1. Verify that the user is signing in with an email address that matches one of the allowed domains for this connection.
  2. If you need to add additional domains to this connection, go to your Clerk Dashboard → SSO Connections → [Your Connection] → Settings, and update the allowed domains.
  3. Alternatively, ensure the user is accessing the correct SAML connection that matches their email domain.

oauth_access_denied

You will encounter this error when the user clicks "Cancel" or "Deny" on the OAuth provider's authorization screen, or when the provider rejects the authorization request.

How to fix it:

  1. Ask the user to try signing in again and ensure they approve the authorization request.
  2. Verify in your Clerk Dashboard → SSO Connections that the OAuth application credentials (Client ID and Client Secret) are correctly configured.

oauth_token_exchange_error

You will encounter this error when Clerk fails to exchange the authorization code for an access token.

How to fix it:

  1. Verify in your Clerk Dashboard → SSO Connections that your OAuth application's Client ID and Client Secret are correctly configured and match the credentials from your OAuth provider's dashboard.
  2. Ensure that the Redirect URI configured in your OAuth provider matches exactly what Clerk expects (including the protocol, domain, and path).

oauth_fetch_user_error

You will encounter this error when Clerk is unable to retrieve the user's profile information from the OAuth provider.

How to fix it:

  1. Verify that the OAuth scopes configured in your Clerk Dashboard → SSO Connections include the necessary permissions to read user profile information.
  2. Ensure that the user info endpoint URL is correctly configured.

Next steps

Now that you've set up Enterprise SSO, you can:

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on