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.

Prerequisites

A Clerk application with the Enhanced authentication add-on(opens in a new tab) plan.

An email_address enabled 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.

The Email, Phone, Username page in the Clerk Dashboard. There is a red arrow pointing to the toggle next to 'Email address', and it is toggled on.

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.

The Enterprise Connections section in the Clerk Dashboard. There is a red arrow pointing to 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.

The Enterprise Connections section in the Clerk Dashboard. The 'Create connection' modal is open.

Once you have filled in these fields, you will be directed to the configuration settings page for the connection you just created.

The configuration settings for the Enterprise connection that was 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.

Different providers use different terminology so consult our glossary table to locate the right term for your case.

The configuration settings for the Enterprise connection that was created. The page is scrolled down to show the 'Service provider details' section.

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.

Different providers use different terminology so consult our glossary table to locate the right term for your case.

The configuration settings for the Enterprise connection that was created. The page is scrolled down to show the 'Identity provider configuration' section.

Map your IdP’s claims to Clerk fields

The last step is to map your IdP claims to Clerk’s email, firstName, 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
`mail` (required)	`user.userprincipalname`	Basic Information > Primary email	`user.email`
`firstName`	`user.givenname`	Basic Information > First name	`user.firstName`
`lastName`	`user.surname`	Basic Information > Last name	`user.lastName`

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 public_metadata_.

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 Canada.

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.

Glossary

Term	Explanation	Azure AD Terminology	Google Terminology	Okta Terminology
`idp_entity_id`	This is the unique identifier of your IdP’s application.	Azure AD Identifier	Entity ID	Identity Provider Issuer
`idp_sso_url`	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
`idp_certificate`	This is the certificate needed for Clerk to securely connect to your IdP.	Certificate (Base64)	Certificate	x.509 Certificate
`sp_entity_id`	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)
`acs_url`	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”.

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.