Add a custom Identity Provider as a SAML connection

Set up an enterprise connection in Clerk

To create a SAML connection in Clerk:

1. Navigate to the Clerk Dashboard.
2. In the top navigation, select Configure. Then in the sidebar, select SSO Connections.
3. Select the Add connection button, and select For specific domains.
4. Select Custom SAML Provider.
5. Add the Name of the connection. This is the name that will be displayed in the sign-in form.
6. Add the Specific Domain that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application.
7. Select Add connection. You will be redirected to the connection's configuration page.

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 Identity Provider

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 on the connection's configuration page, under Identity Provider Configuration,select Add via metadata. Input the metadata URL or upload the metadata file that you got from your IdP.

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, paste the values you copied from your IdP into the appropriate fields, and upload the certificate you got from your IdP.

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, on the connection's configuration page, 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.

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, you should still have the connection's configuration page open. If not, navigate to the SSO Connections page and select the connection.
2. Toggle on Enable connection and select Save.

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.