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
- An Application in the Business plan.
- You need to have
email_addressenabled as a strategy follow this Dashboard to enable it, if it’s not already active).
Your existing users will not be able to sign in with SAML, as we don't currently support account merging. Once you set up SAML, you'll need to delete your existing users and have them sign in with SAML.
Create a SAML connection
Get started by creating a SAML Connection by visiting the Enterprise Connections section in your Dashboard. Alternatively, you can use the API as described in the backend API reference.
These are the fields that you need to fill in (they are all required):
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.
We currently don’t verify that the emails in this domain belong to your users, so if you accidentally set up a untrusted Identity Provider, or plan to implement self-service SSO in your services, you may enable account takeovers
IdP Entity ID- This is the unique identifier of your IdP application. Different providers use different terminology so consult our glossary table to locate the right term for your case.IdP SSO URL- This is your IdP’s URL that we’ll redirect your users to so that they authenticate. Different providers use different terminology so consult our glossary table to locate the right term for your case.Certificate- This is the certificate needed for Clerk to securely connect to your IdP.
Update your IdP Application
The response of your created connection includes two fields that you will need to add to your IdP’s application:
SP Entity ID- This is a unique identifier for your SAML connection that your IdP application needs. Different providers use different terminology so consult our glossary table to locate the right term for your case.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.
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, the last two are for getting the user’s 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 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".
Read here on 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 Dashboard. We do this so that 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
FAQ
I’ve enabled other strategies but they don’t work.
It is expected that once Enterprise SSO is enabled in an organization, 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?
At the time being, SAML flow doesn't support account merging. That means, that if you enable SAML, any existing users that their email address matches the SAML Connection domain, won't be able to authenticate.
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.