Add Microsoft Entra ID 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.
3. In the modal that opens, select Microsoft Entra ID (Formerly AD) as the identity provider.
4. Add the Name of the connection. This is the name that will be displayed on the sign-in form.
5. Enter 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 app.
6. Select Add connection. You'll be redirected to the connection's configuration page.
7. Find the Service Provider Configuration section.
8. Save the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) values somewhere secure. You'll need these in the Configure your service provider step. Leave this page open.

Create a new enterprise app in Microsoft

To create a new enterprise app in Microsoft:

1. In a separate page, 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:

• Enter the Name of your app.
• Ensure the option Integrate any other application you don't find in the gallery (Non-gallery) is selected.
• Select Create.

Assign selected user or group in Microsoft

Now that you have created the enterprise app, you need to assign users or groups to the app. For example, if you were part of the Clerk organization, you would have access to users and groups within the Clerk organization. In this case, you could assign individual users or entire groups to the enterprise app you just created.

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.

Configure SSO in Microsoft

After assigning the user or group to the enterprise app, you need to configure the SSO settings to enable SAML SSO.

1. In the navigation sidebar, open the Manage dropdown and select Single sign-on.
2. In the Select a single sign-on method section, select SAML.

Configure your service provider

To configure Clerk as your service provider, add these two fields to your IdP's application:

• Identifier (Entity ID) - A unique identifier for your SAML connection, required by your IdP app.
• Reply URL (Assertion Consumer Service URL) - The URL of your app where your IdP will redirect your users after they authenticate.

To complete the following values for these fields:

1. On the Set up Single Sign-On with SAML page, find the Basic SAML Configuration section.
2. Select Edit to open the Basic SAML Configuration panel.
3. Paste the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) values you saved earlier into their respective fields. These values will be saved automatically.
4. Select Save at the top of the panel. Close the panel.

Configure your identity provider

To configure Microsoft Entra ID as your identity provider, add the following fields to your app:

1. On the Set up Single Sign-On with SAML page, find the SAML Certificates section.
2. Copy the App Federation Metadata Url.
3. Navigate back to the Clerk Dashboard. In the Identity Provider Configuration section, under App Federation Metadata Url, paste the App Federation Metadata URL.
4. Select Fetch & save.

Map Microsoft claims to Clerk attributes

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.

The only Microsoft claim that is necessary to map is the email address claim. This is the email address that your users will use to log in to your app.

1. Navigate back to the Microsoft Azure portal.
2. On the Set up Single Sign-On with SAML page, find the Attributes & Claims section.
3. Select Edit.
4. To edit the email claim, select the claim with the value of user.email. You'll be redirected to the Manage claim page.
5. Next to Source attribute, search for and select user.userprincipalname in the dropdown.
6. Select Save at the top of the page.

Enable the connection for Clerk

To make the connection available for your 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.

Test your OAuth

The simplest way to test your OAuth is to visit your Clerk app's Account Portal, which is available for all Clerk apps out-of-the-box.

1. In the Clerk Dashboard, navigate to the Account Portal page.

2. Next to the Sign-in URL, select Visit. The URL should resemble:

   • For development – https://your-domain.accounts.dev/sign-in
   • For production – https://accounts.your-domain.com/sign-in

3. Sign in with your Microsoft account.