Use a custom Identity Provider for SAML SSO

Set up an enterprise connection in Clerk

To create a SAML connection in Clerk:

1. Navigate to the Clerk Dashboard⁠.
2. In the navigation sidebar, select User & Authentication > Enterprise Connections⁠.
3. Select the Create connection button.
4. You will be presented with a modal to create a new connection. Fill in the required fields and for the Identity Provider, select Custom.
5. Next, on the Connection page, do not select the Enable connection toggle just yet. You need to fully configure your IdP first before exposing your connection to your users.
6. Leave this page open. You will need to come back to it to complete the setup.

Create a new enterprise application in your IdP

Create a new application in your IdP. In the next steps, you will configure your IdP with the settings provided by your Service Provider (Clerk), and you will configure Clerk with the settings provided by your IdP. So, you will need to keep both the IdP and Clerk dashboards open.

Configure your Service Provider

To configure your Service Provider (Clerk), your IdP will either ask for the Assertion Consumer Service (ACS) URL and Entity ID or it will ask for the Metadata URL. If your IdP gives you the option to choose between the two, it is recommended to choose the Metadata URL as it is the quickest and most reliable way to configure your Service Provider.

Here are what these settings mean:

• Assertion Consumer Service (ACS) URL - This is your application's URL that your IdP will redirect your users back to after they have authenticated in your IdP.
• Entity ID - This is a unique identifier for your SAML connection that your IdP application needs.
• Metadata URL - This is the URL to your SAML connection's metadata file. This is the recommended way to configure your Service Provider.

To find the values for these settings:

1. In the Clerk Dashboard, find the Service Provider configuration section.
2. Copy the values you need for your IdP.
3. In your IdP dashboard, paste the values in the appropriate fields.

Configure your Identity Provider

To configure your IdP in Clerk, scroll down to the Identity Provider configuration section. There are two options for configuring your IdP:

• Metadata configuration - This is where you can download your IdP's metadata file or input the metadata URL that you got from your IdP. This is the recommended way to configure your IdP, but not all IdPs support this method.
• Custom configuration - This is where you can manually input the configuration settings for your IdP.

Metadata configuration

1. In your IdP dashboard, find where you can download the metadata file or copy the metadata URL.
2. In the Clerk Dashboard, find the Identity Provider configuration section.
3. Under the Metadata configuration option, input the metadata URL or upload the metadata file that you got from your IdP.
4. Select the Save changes button to complete the setup.

Custom configuration

If you choose to manually input the configuration settings for your IdP, you will need to fill these three fields in the Clerk Dashboard:

• SSO URL - This is your IdP's URL that Clerk will redirect your users to so that they authenticate.
• Entity ID - This is the unique identifier of your IdP application.
• Certificate - This is the certificate needed for Clerk to securely connect to your IdP.

1. In your IdP dashboard, find these values and copy them.
2. In the Clerk Dashboard, find the Identity Provider configuration section.
3. Select the Custom configuration option.
4. Paste the values you copied from your IdP into the appropriate fields.
5. Select the Save changes button to complete the setup.

Map your IdP's claims to Clerk fields

Mapping the claims in your IdP to the attributes in Clerk ensures that the data from your IdP is correctly mapped to the data in Clerk.

In the Clerk Dashboard, find the Attribute mapping section. Here, you are shown what properties on the User object in Clerk are being mapped to the claims in your IdP.

In your IdP dashboard, there should be a section where you can map the IdP's claims to the attributes in Clerk. For example, Google has a Primary email claim that needs to be mapped to Clerk's mail property. During SAML configuration in the Google dashboard, Google provides a section where these claims can be mapped.

If you have additional claims that you would like to map to Clerk that are not listed in the Attribute mapping section, you can do so by following the steps in the Map other claims section.

Map other claims (optional)

In Clerk, the User object has a publicMetadata property that you can use to store additional information about your users.

To map other claims from your IdP that do not have a direct mapping to Clerk attributes, you can map them to the publicMetadata property. To do this, prepend the Clerk claims with public_metadata_ during the mapping process.

For example, say you were using Google as your IdP. Google users have the "Phone number" attribute. Clerk does not have a direct mapping for this attribute, as you can see in the Clerk Dashboard in the Attribute mapping section. Instead, in the Google dashboard, you would map Google's "Phone number" claim to public_metadata_phone_number. Then, in Clerk, the value for the user's phone number would be saved in the user's User.publicMetadata under the key phone_number.

Learn more about how to access the metadata from our APIs.

Activate your SAML connection

Now that you have configured your SAML connection, you can activate it.

To make the connection available for your users to authenticate with:

1. In the Clerk Dashboard, scroll to the top of the Connection page.
2. Toggle on the Enable connection option.

Test your SAML connection

Everything should be set up now for you to test authentication via SAML. Go to your Clerk application's sign-in page and add your email address in the input field. If it matches an active SAML connection, you will be redirected to your IdP where you will sign in with your credentials.