Add a custom Identity Provider (IdP) as a SAML connection

Set up an enterprise connection in Clerk

To create a SAML connection in Clerk:

1. In the Clerk Dashboard, navigate to the SSO connections⁠ page.
2. Select Add connection and select For specific domains or organizations.
3. Under SAML, select Custom SAML Provider.
4. Add the Domain for which you want to enable this connection. This is the domain of the users you wish to allow to sign in to your application. Optionally, select an Organization.
5. Enter the Name. This will be displayed on the sign-in form.
6. Select Add connection. You'll 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'll configure your IdP with the settings provided by your Service Provider (Clerk), and configure Clerk with the settings provided by your IdP. Keep both the IdP and Clerk Dashboard 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, open the connection and select the SSO tab. 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 page, select the SSO tab and find the Service Provider configuration card.
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, on the SSO tab of your connection, find the Attribute mapping card. The Common attributes section shows the properties that are mapped from your IdP's claims to the Clerk User object. The Custom attributes section is where you'll map any additional custom attributes you've defined. Refer to Map other claims.

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)

For IdP claims with no direct Clerk equivalent, you can store them in User.publicMetadata. There are two ways to do this depending on your setup.

1. If you only use SSO (no Directory Sync), prefix the Clerk claim name with public_metadata_ when configuring the mapping in your IdP. For example, to store Google's "Phone number" attribute, map it to public_metadata_phone_number in the Google dashboard. Clerk will save the value under the key phone_number in User.publicMetadata.

   Note

   Some IdPs (like Microsoft Entra) format additional claims as URLs. Map these as plain strings so they work correctly with Clerk.

2. If you use both SSO and Directory Sync, use custom attributes instead — they apply to both SSO and SCIM, so your attribute definitions stay consistent across both. Custom attributes are defined at the enterprise connection level and sync fields like department or employee_id into User.publicMetadata.

   Setup is a two-step process:

   1. Define the attributes on the Overview tab, in the Identity provider attributes card.
   2. Map them to SAML claim paths on the SSO tab, in the Custom attributes section of the Attribute mapping card.

   For a full walkthrough, see Custom Attribute Mapping.

   Note

   When Directory Sync is enabled, SCIM becomes the sole source for custom attribute values and overrides SSO. Custom attributes can be edited via SSO again once Directory Sync is disabled.

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

Enable the connection for Clerk

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

1. In the Clerk Dashboard, you should still have the connection's page open. If not, navigate to the SSO connections⁠ page and select the connection.
2. In the actions bar at the top of the page, select Enable SSO connection. (If required IdP fields are missing, the button opens a dialog listing what's needed first.)