Skip to main content

Add Microsoft Entra ID as a SAML connection

Before you start

Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP).

When you configure a SAML connection with Microsoft Entra ID (formerly Azure Active Directory) as your IdP, your users can sign up and sign in to your application with their Microsoft account. In this guide, you configure the connection in the Clerk Dashboard, while the customer (whoever manages the Microsoft Entra ID application) configures it on the Microsoft side.

Tip

This guide requires coordination between you and your customers' IT administrators. If you're creating an enterprise connection for an Organization, you can allow your customers' IT admins to configure SSO themselves. See the guide on self-serve SSO for more information.

Create a Microsoft Entra ID 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 Microsoft Entra ID (Formerly AD).
  4. Enter the Domain. This is the email domain of the users you want 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. Note that the connection is disabled by default.
  7. In the Service Provider Configuration section, save the Reply URL (Assertion Consumer Service URL) and Identifier (Entity ID) values somewhere secure. You'll need to give these to the customer so they can configure their Microsoft Entra ID application.

Configure SAML application

Now that the enterprise connection is configured in Clerk and the Reply URL and Identifier are known, the customer's Microsoft application needs to be configured. At a high level, the process is:

  • Create a new enterprise application in Microsoft Azure and assign users or groups.
  • Add the Reply URL and Identifier from Clerk to the application's SAML configuration.
  • Configure the attribute claims.
  • Share the application's App Federation Metadata URL.

To get you started, you can use the following email template with detailed instructions. Remember to share the Reply URL and Identifier (Entity ID):

Here are the instructions for setting up SAML SSO with Microsoft Entra ID:

Step 1: Create a new enterprise application

  1. Sign in to the Microsoft Azure portal and go to Enterprise applications.
  2. Select New application, then Create your own application.
  3. In the modal that opens, enter your application name, select Integrate any other application you don't find in the gallery (Non-gallery), then select Create.
  4. In the Getting Started section, select Assign users and groups. (For group options, see Microsoft's docs.)
  5. Select Add user/group, choose the users or groups to assign, then select Assign.

Step 2: Add your service provider details

  1. In the side navigation, open the Manage dropdown and select Single sign-on.
  2. In the Select a single sign-on method section, select SAML.
  3. Find the Basic SAML Configuration section and select Edit.
  4. Copy the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) values provided to you into their respective fields.
  5. Select Save, then close the panel.

Step 3: Configure attributes and claims

Your SAML response must include the following attributes:

AttributeRequiredClaim nameValue
Email address✅http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressuser.mail
First name❌http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameuser.givenname
Last name❌http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameuser.surname

These are usually the defaults, but it's worth confirming, since many SAML errors come from incorrect attribute mappings. On the SAML-based Sign-on page, find the Attributes & Claims section, select Edit, and verify the attributes above are present.

Step 4: Share the application's metadata URL

On the SAML-based Sign-on page, find the SAML Certificates section, copy the App Federation Metadata Url, and reply to this email with it.

Add App Federation Metadata URL in the Clerk Dashboard

After following the instructions in the email, your customer should have sent you the Microsoft app's App Federation Metadata URL. Now, you're going to add it to the Clerk connection, completing the SAML connection configuration.

  1. Navigate to the SSO connections page in the Clerk Dashboard.
  2. Select the SAML connection.
  3. In the Identity Provider Configuration section, under App Federation Metadata Url, paste the App Federation Metadata URL.
  4. Select Fetch & save. Keep the page open for the next step.

Map IdP claims to Clerk fields

Clerk automatically maps the standard SAML claims (email, first name, and last name) to the User object. To review them, open the connection's SSO tab and find the Common attributes section under Attribute mapping.

To map a claim that has no standard Clerk field, store it in the user's publicMetadata. The approach depends on whether the connection also uses Directory Sync:

  • SSO only: In the IdP, prefix the claim name with public_metadata_. For example, mapping a phone number to public_metadata_phone_number stores it under phone_number in User.publicMetadata. Some IdPs, such as Microsoft Entra, send claims as URLs; map those as plain strings.
  • SSO with Directory Sync: Define a custom attribute so the mapping applies to both SSO and SCIM. Define it on the connection's Overview tab (in the Identity provider attributes section), then map it in the SSO tab (in the Custom attributes section of the Attribute mapping section). Refer to the guide on custom attribute mapping. While Directory Sync is enabled, SCIM is the only source for these values and overrides SSO.

Learn more about accessing user metadata from the API.

Enable the connection in Clerk

You have configured the SAML connection. Once enabled, all users with email addresses ending in the domain will be redirected to your identity provider at sign-up and sign-in.

Warning

If the SAML configuration in Clerk or your identity provider has an error, existing users with matching email domains will be unable to sign in once the connection is enabled. We recommend coordinating with your counterpart to test the connection at an off-peak time.

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

  1. Navigate to the SSO connections page and select the connection.
  2. At the top of the page, toggle on Enable connection and select Save.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub