unleash.unleash/website/docs/how-to/how-to-add-sso-azure-saml.mdx

---
title: How to add SSO with SAML 2.0 and Microsoft Entra ID
description: 'Configure Microsoft Entra ID SSO with SAML 2.0 for your Unleash instance.'
---

import Figure from '@site/src/components/Figure/Figure.tsx'

:::note Availability

**Plan**: [Enterprise](https://www.getunleash.io/pricing)

:::

This guide walks you through setting up single sign-on (SSO) using SAML 2.0, with [Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) as the identity provider (IdP). Unleash supports a variety of identity providers and protocols; visit our [reference documentation](../reference/sso.md) to explore other options.

## Prerequisites

To follow along, you'll need:

- An Unleash instance with [Admin access](../reference/rbac.md).
- Access to Microsoft Entra as at least a [Cloud Application Administrator](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/permissions-reference#cloud-application-administrator).

## Create an enterprise application in Microsoft Entra ID

To create a new enterprise application in Microsoft Entra, do the following:
1. In the Microsoft Entra admin center, go to **Identity > Applications > Enterprise applications** and click **New application**.
2. In the Microsoft Entra Gallery, click **Create your own application**.
3. Enter an app name, select the **Integrate any other application you don't find in the gallery** option, and click **Create**.

## Configure SAML SSO for the application

### Add SAML configuration

To configure SSO for the new application, do the following:
1. In the overview page of the application, go to **Manage > Single sign-on** and click **SAML**.
2. In the **Basic SAML Configuration** section, click **Edit**.
3. Click **Add identifier** and enter the Unleash identifier. For hosted instances, that is `https://<region>.app.unleash-hosted.com/<your_unleash_instance_name>`.
4. Click **Add reply URL** and enter the URL shown in the Unleash Admin UI at **Admin > Single sign-on > SAML 2.0**. For example, `<your_unleash_url>/auth/saml/callback`.
5. Click **Save**.

### Manage attributes and claims

To configure attributes and claims for the new application, do the following:
1. In the single sign-on settings of your application, go to **Attributes & Claims** and click **Edit**.
2. Go to **Required claim** and click **Unique User Identifier (Name ID)**.
3. For **Name identifier format**, select **Email address**.
4. For **Source**, select **Attribute** and for **Source attribute** select `user.mail`.
5. Click **Save**.

To populate the first and last names of users in Unleash, configure two additional claims with attributes `user.givenname` and `user.surname` with no namespace.

<Figure caption="Edit the SAML configuration in Microsoft Entra admin center." img="/img/microsoft-entra-claims.png" />


### Save SAML certificate, identifier, and login URL

Save the following information from the single sign-on settings of your application:
- [SAML certificate](#saml-certificate)
- [Login URL](#login-url)
- [Microsoft Entra Identifier](#microsoft-entra-identifier)

#### SAML certificate
To save the SAML certificate, go to the single sign-on settings of your application. In **SAML Certificates > Federation Metadata XML**, click **Download**. Open the file and copy the contents between the `X509Certificate` tag. 

<Figure caption="Save the X509 Certificate from the SAML certificate XML file. The example has been redacted." img="/img/x509cert.png" />

#### Login URL
To find your login URL, go to the single sign-on settings of your application. In the **Set up `<your-application-name>`** section, copy and save **Login URL**. For example: `https://login.microsoftonline.com/<your_identifier>/saml2`.

#### Microsoft Entra identifier

To find your Microsoft Entra identifier, go to the single sign-on settings of your application. In the **Set up `<your-application-name>`** section, copy and save **Microsoft Entra Identifier**. For example: `https://sts.windows.net/<your_identifier>`


## Configure the SAML 2.0 provider in Unleash

To finalize the configuration, do the following:

1. In the Unleash Admin UI, go to **Admin > Single sign-on > SAML 2.0**.
2. In **Entity ID**, enter your [Microsoft Entra identifier](#microsoft-entra-identifier).
3. In **Single sign-on URL**, enter your [Login URL](#login-url).
4. In **X.509 Certificate**, [enter your SAML certificate](#saml-certificate).
5. Optional: To automatically create users for first-time sign-ins, select **Auto-create users**. Select a default root role new users should have, and configure the list of valid email domains.
6. Click **Save**.

<Figure caption="Configure SAML 2.0 in Unleash." img="/img/saml2.0.png" />

## Test your configuration

To test that things are working as expected, log out of Unleash and verify that the login screen gives you the option to sign in with SAML 2.0. You can also test the integration in Microsoft Entra in the single sign-on settings of your application.

## Enable group syncing

Optionally, you can sync groups from Microsoft Entra ID to Unleash to [map them to groups in Unleash](./how-to-set-up-group-sso-sync.md).

To create the group in Microsoft Entra, do the following:
1. In the Microsoft Entra admin center, go to the single sign-on settings of your application, and select **Attributes & Claims**.
2. Click **Add a group claim** and select **Groups assigned to the application**.
3. In the **Advanced options** click **Customize the name of the group claim**, and enter a name.
4. Click **Save**.

:::info Note
Microsoft Entra limits the number of groups emitted in a SAML response to 150, including nested groups. If you have users who are present in more than 150 groups, add a filter in the advanced section of group claims to ensure the response only includes the groups you want to send to Unleash.
:::

To enable group syncing in Unleash, do the following:
1. In the Unleash Admin UI, go to **Admin > Single sign-on > SAML 2.0**.
2. Select **Enable Group Syncing** and add the name in your group in Group Field JSON Path.
3. Click **Save**.