Use Microsoft Azure AD for SAML SSO

Set up an enterprise connection in Clerk

To create a SAML connection in Clerk:

1. Navigate to the Clerk Dashboard.
2. In the navigation sidebar, select User & Authentication > Enterprise Connections.
3. Select the Create connection button.
4. You will be presented with a modal to create a new connection. Fill in the required fields and for the Identity Provider, select Microsoft Azure AD.
5. Next, on the Connection page, do not select the Enable connection toggle just yet. You need to fully configure your IdP first before exposing your connection to your users.
6. Leave this page open. You will need to come back to it to complete the setup.

Create a new enterprise application in Azure

To create a new enterprise application in Azure:

1. Navigate to the 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 the New Application button.
4. Select the Create your own application button.
5. Fill in the required fields and select the Create button.

Assign selected user or group in Azure

Now that you have created the enterprise application, you need to assign your users/user groups to it. For example, if you were part of the Clerk organization, you would have access to users and groups in the Clerk organization. In this case, you could assign one or more users or entire groups to the enterprise application you just created.

1. Under the Getting started section, select Assign users and groups.
2. Select the Add user/group button.
3. Under Users, select the None Selected link.
4. In the search field, enter the user or group of users that you want to assign to the enterprise application.
5. Select the check box next to the user or group that you want to assign.
6. Select the Select button at the bottom of the page.
7. Select the Assign button at the bottom of the page.

Configure single sign-on (SSO) in Azure

After you have assigned the user or group of users to the enterprise application, you need to configure the single sign-on (SSO) settings to enable SAML SSO.

1. In the navigation sidebar, select Overview.
2. Under the Getting started section, select Set up single sign-on.
3. Select SAML as the single sign-on method.

Configure your service provider

To configure your service provider (Clerk), you must add these two fields to your IdP's application:

• Reply URL (Assertion Consumer Service URL) - This is a unique identifier for your SAML connection that your IdP application needs.
• Identifier (Entity ID) - This is your application's URL that your IdP will redirect your users back to after they have authenticated in your IdP.

To fill out the appropriate values for these fields:

1. On the Set up Single Sign-On with SAML page, you will see the Basic SAML Configuration section. Select the Edit button. This will open a Basic SAML Configuration modal.
2. Go back to the Clerk Dashboard and scroll down to the Service Provider configuration section.
3. Copy the Identifier (Entity ID) and the Reply URL (Assertion Consumer Service URL).
4. In the Azure Portal, in the Basic SAML Configuration modal, paste these values into their respective fields.
5. Select Save at the top of the modal.

Configure your identity provider

1. On the Set up Single Sign-On with SAML page, find the SAML Certificates section.
2. Copy the App Federation Metadata Url.
3. In the Clerk Dashboard, find the Identity Provider configuration section.
4. Under the Metadata configuration option, paste the App Federation Metadata Url.

Map Azure 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 Azure 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 application.

1. On the Set up Single Sign-On with SAML page, find the Attributes & Claims section.
2. Select the Edit button.
3. Select the email address claim (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress) to edit the field.
4. Next to Source attribute, select the dropdown and choose user.userprincipalname.
5. 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. In the Clerk Dashboard, scroll to the top of the Connection page.
2. Toggle on the Enable connection option.