Skip to main content
Docs
Dashboard

Add Microsoft Entra ID as a SAML connection

Before you start

Enabling SAML with Microsoft Entra ID (formerly Azure Active Directory) allows your users to sign up and sign in to your Clerk application with their Microsoft account.

This process requires configuration changes in both the Clerk Dashboard, and in your customer's Microsoft Entra ID settings in their Azure account.

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 app in Microsoft Azure.
  • Assign selected users or groups to that Microsoft application.
  • Add the Reply URL and Identifier from Clerk to the Microsoft application's SAML configuration.
  • Verify that the attribute mappings are correct.
  • Obtain and share the application's metadata URL.

You are welcome the use the below email template with detailed instructions. They contain the following template strings that you should replace with your actual values:

  • [YOUR_APPLICATION_NAME]
  • [YOUR_CLERK_ENTITY_ID]
  • [YOUR_CLERK_REPLY_URL]

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

Step 1: Create a new enterprise application in Microsoft

  1. Navigate to the Microsoft Azure portal and sign in.
  2. Under the Azure Services section, find and select Enterprise applications. You may have to go to the All services page and then scroll down to the Identity section to find it.
  3. Select New application. You'll be redirected to the Browse Microsoft Entra Gallery page.
  4. Select Create your own application.
  5. In the modal that opens:
    • Name of your application (likely [YOUR_APPLICATION_NAME]).
    • Select Integrate any other application you don't find in the gallery (Non-gallery).
    • Select Create.

Step 2: Assign your users or groups in Microsoft

Now that you have created the enterprise app, you need to assign users or groups before they can use it to log in. Below are instructions for assigning an individual user, but for more options and instructions for groups, see Microsoft's docs here.

  1. In the Getting Started section, select the Assign users and groups link.
  2. Select Add user/group. You'll be redirected to the Add Assignment page.
  3. Select the None Selected link.
  4. To assign a user to the enterprise app, you can either use the search field to find a user or select the checkbox next to the user in the table.
  5. Select Select at the bottom of the page. You'll be redirected to the Add Assignment page.
  6. Select Assign at the bottom of the page.

Step 3: Set Basic SAML Configuration

  1. In the navigation sidenav, open the Manage dropdown and select Single sign-on.
  2. In the Select a single sign-on method section, select SAML. You'll be redirected to the Set up Single Sign-On with SAML page.
  3. Find the Basic SAML Configuration section.
  4. Select Edit. The Basic SAML Configuration panel will open.
  5. Add the following Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) values. These values will be saved automatically.
    • Identifier (Entity ID): [YOUR_CLERK_ENTITY_ID]
    • Reply URL (Assertion Consumer Service URL): [YOUR_CLERK_REPLY_URL]
  6. Select Save at the top of the panel. Close the panel.

Step 4: Verify correct configuration of attributes and claims

We expect your SAML responses to have the following specific attributes:

Email address (required). This is the email address that your users will use to authenticate into your app:

  • Claim name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • Value: user.mail

First name (optional):

  • Claim name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • Value: user.givenname

First name (optional):

  • Claim name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
  • Value: user.surname

These are the defaults, and probably won't need you to change them. However, many SAML configuration errors are due to incorrect attribute mappings, so it's worth double-checking. Here's how:

  1. Still on the Set up Single Sign-On with SAML page, find the Attributes & Claims section.
  2. Select Edit.
  3. Verify that the above three attributes and values are present.

Step 5: Share the application's metadata URL

  1. Still on the Set up Single Sign-On with SAML page, find the SAML Certificates section.
  2. Copy the App Federation Metadata Url, and reply to this email with it. This is the final piece of information we need to enable SAML.

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.

Enable the connection in Clerk

The SAML connection is ready to enable! Once enabled, all users with email addresses ending in the domain will be redirected to Microsoft at sign-up and sign-in.

Warning

If there are existing users with email domains that match the SAML connection, and there is an error in the SAML configuration in Clerk or Microsoft, those users will be unable to sign in when the connection is enabled. If this is a concern, we recommend coordinating with your counterpart to test the connection at an off-peak time.

To make the connection available for users to authenticate with:

  1. Navigate back to the Clerk Dashboard where you should still have the connection's configuration page open. If not, 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?
Edit this page on GitHub

Last updated on