SAML at Clerk (Beta)
Clerk supports Enterprise SSO via the SAML protocol so that you can create authentication strategies for Identity Providers, such as Okta.
- A Clerk application with the Enhanced authentication add-on(opens in a new tab) plan.
email_addressenabled as a strategy. In the Clerk Dashboard, go to User & Authentication > Email, Phone, Username(opens in a new tab). In the Contact information section, enable the Email address strategy by toggling on the switch.
Create a SAML connection
To create a SAML Connection, in the Clerk Dashboard, go to User & Authentication > Enterprise Connections(opens in a new tab).
Click on the Create connection button.
Once you have clicked on the Create connection button, you will be presented with a modal to create a new connection. Fill in the required fields.
- Name - A unique name for the connection. This is so you can tell your connections apart.
- Domain - This is the email domain for which you will enable Enterprise SSO.
Once you have filled in these fields, you will be directed to the configuration settings page for the connection you just created.
Scroll down to the Service provider details section. You will need to add these two fields to your IdP’s application:
- SP Entity ID - This is a unique identifier for your SAML connection that your IdP application needs.
- ACS URL - This is your application’s URL that your IdP will redirect your users back to after they have authenticated in your IdP.
Scroll down to the Identity provider configuration section. Here, you will see:
- IdP Entity ID - This is the unique identifier of your IdP application.
- IdP SSO URL - This is your IdP’s URL that we’ll redirect your users to so that they authenticate.
- Certificate - This is the certificate needed for Clerk to securely connect to your IdP.
Map your IdP’s claims to Clerk fields
The last step is to map your IdP claims to Clerk’s
lastName fields. The first is required for the integration to work and the last two are required for getting the user’s name.
|Azure AD Claim Names
|Google Claim Names
|Okta Claim Names
|Basic Information > Primary email
|Basic Information > First name
|Basic Information > Last name
Map every other claim
If you wish to map other claims from your IdP, you can do so by mapping them to your users' public metadata. You do this by prepending the Clerk claims with
For example, the claim
public_metadata_country with the value
Canada will be saved in the user's
public_metadata under the key
country with the value
Learn more about how to access the metadata from our APIs.
Activate your SAML Connection
Now that everything is set up, you need to activate the SAML Connection via the Clerk Dashboard. This is so you don't expose your connection to your users while you're in the, sometimes long, process of configuring and testing it.
Authenticate with SAML
Everything should be set up now for you to try out authentication via SAML. Go to your application’s Sign In page and add your email in the input field. If it matches an active SAML Connection, you will be redirected to your IdP where you will log in with your credentials.
|Azure AD Terminology
|This is the unique identifier of your IdP’s application.
|Azure AD Identifier
|Identity Provider Issuer
|This is your IdP’s URL that we’ll redirect your users to so that they authenticate.
|Identity Provider Single Sign-On URL
|This is the certificate needed for Clerk to securely connect to your IdP.
|This is a unique identifier for your SAML connection that your IdP application needs.
|Identifier (Entity ID)
|Entity ID (Under “Service Provider Details”)
|Audience URI (SP Entity ID)
|This is your application’s URL that your IdP will redirect your users back to after they have authenticated in your IdP.
|Reply URL (Assertion Consumer Service URL)
|Single sign-on URL
|This is the protocol that we are using to connect to your Identity Provider. Other protocols are OIDC, OAuth 2.0.
|This is the connection that you create in Clerk to hold the integration configuration.
|This is the service you are using to store your users’ identity. Azure AD and Okta are two popular providers.
|Abbreviation for “Identity Provider”
|This is an application from the IdP that connects to
|This is the service that requests and receives the identity from the IdP.
|Abbreviation for “Service Provider”.
Frequently asked questions (FAQ)
I’ve enabled other strategies but they don’t work.
A Clerk application can have multiple authentication strategies, but a domain that enables Enterprise SSO can not. Once Enterprise SSO is enabled for a domain, there can be no other authentication methods for that specific domain. This is in line with an organization’s intent to manage their users’ identity from one place. This will allow your Clerk application to enable Enterprise SSO connections for certain domains while others use non-Enterprise SSO methods depending on each organization's needs.
Will SAML work for my existing users?
Yes, SAML will work for your existing users as well! That means, that if you enable SAML, any existing users that their email address matches the SAML Connection domain, they will have to authenticate on the IdP side and an Enterprise Account will be linked to their existing account.
What happens if I have multi-factor enabled at Clerk?
This will work: Once the user comes back from the IdP, they will need to go through the extra factors of authentication. This is in case you need to add extra factors on top of what your IdP supports (or in case they don’t). You can choose to not enable this feature if you wish.
What happens if I delete the SAML connection? Will my users be deleted?
The users will not be deleted, so your application will not break. However, they will need to “reintroduce” themselves to your new strategies by resetting their passwords or via OTP (depending on the strategy you choose).
Does Clerk support IdP-initiated SSO?
No, Clerk only supports SP-initiated flows at this time.
How much does it cost now?
It’s going to be free during the Beta period.
How much will it cost after Beta?
It will cost $50 per active connection per month for production instances. Connections in development instances are and will be free, but capped to 5.
Can I get a bulk discount?
Yes, reach out to us(opens in a new tab) and we will work a plan out.
Last updated on January 29, 2024