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 Business plan.
email_addressenabled as a strategy. To do so, navigate to the Email, Phone, Username section of the Clerk Dashboard. In the Contact information section, enable the Email address strategy by toggling on the switch.
Create a SAML connection
To create a SAML Connection, get started by visiting the Enterprise Connections section in the Clerk Dashboard.
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.
|Clerk Field||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.
|Term||Explanation||Azure AD Terminology||Google Terminology||Okta Terminology|
|This is the unique identifier of your IdP’s application.||Azure AD Identifier||Entity ID||Identity Provider Issuer|
|This is your IdP’s URL that we’ll redirect your users to so that they authenticate.||Login URL||SSO URL||Identity Provider Single Sign-On URL|
|This is the certificate needed for Clerk to securely connect to your IdP.||Certificate (Base64)||Certificate||x.509 Certificate|
|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)||ACS URL||Single sign-on URL|
|SAML||This is the protocol that we are using to connect to your Identity Provider. Other protocols are OIDC, OAuth 2.0.|
|SAML Connection||This is the connection that you create in Clerk to hold the integration configuration.|
|Identity Provider||This is the service you are using to store your users’ identity. Azure AD and Okta are two popular providers.|
|IdP||Abbreviation for “Identity Provider”|
|IdP Application||This is an application from the IdP that connects to|
|Service Provider||This is the service that requests and receives the identity from the IdP.|
|SP||Abbreviation for “Service Provider”.|
I’ve enabled other strategies but they don’t work.
It is expected that once Enterprise SSO is enabled in an application, there should be no other authentication methods applicable. This is in line with an organization’s intent to manage their users’ identity from one place.
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).
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 connection 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 and we will work a plan out.