# Microsoft Azure Entra ID (formerly Azure AD) SSO Setup


{{< announcement >}}
The Single Sign-On feature is available in the [Enterprise](https://www.rudderstack.com/enterprise-quote/) plan only.
{{< /announcement >}}

This guide lists the steps to set up your Azure Entra ID SAML integration with RudderStack.

## Overview

This integration supports the following features:

- SP-initiated SSO
- JIT(Just In Time) Provisioning

{{< info >}}
Note that:

- RudderStack supports only the [SAML 2.0 protocol](https://auth0.com/intro-to-iam/what-is-saml) for SSO.
- RudderStack does not support some SCIM features like importing users and groups, removing users, and syncing passwords. See [Known issues](#known-issues) before you set up SSO for your organization.
{{< /info >}}

## Step 1: Create new application

1. Sign in to [Microsoft Entra ID Admin Center](https://entra.microsoft.com/).
2. From the left sidebar, go to **Applications** > **Enterprise applications**.
3. Under **Manage**, click **All applications** followed by **New application**.

{{< image src="images/user-guides/azure-sso/rudderstack-azure-sso-1.webp" alt="New application option" >}}

4. In the **Microsoft Entra App Gallery**, click **Create your own application**.

{{< image src="images/user-guides/azure-sso/rudderstack-azure-sso-2.webp" alt="Create your own application option" >}}

5. In the expanded right sidebar, enter the name of your app. 
6. Under **What are you looking to do with your application?**, select **Integrate any other application you don't find in the gallery (Non-gallery)**.

{{< image src="images/user-guides/azure-sso/rudderstack-azure-sso-3.webp" alt="Initial configuration" >}}

7. Click the **Create** button at the bottom and wait for a few seconds for Azure to provision the app. You will then be redirected to the admin view of the app.

## Step 2: Set up SAML

1. In the left sidebar of the newly provisioned app, click **Single sign-on** under **Manage**. Then, click **SAML**.

{{< image src="images/user-guides/azure-sso/rudderstack-azure-sso-5.webp" alt="SAML SSO method" >}}

2. Click the meatballs menu (`...`) to the right of **Basic SAML Configuration**. In the expanded right sidebar, fill in the following information:

| Field |  Value | 
| :-- | :----| 
| Identifier (Entity ID) <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `urn:amazon:cognito:sp:us-east-1_ABZiTjXia` |
| Reply URL (Assertion Consumer Service URL) <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> |  `https://auth2.rudderstack.com/saml2/idpresponse` | 
| Sign on URL <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `https://app.rudderstack.com/sso?domain=<YOUR_EMAIL_DOMAIN>` <br /><br />{{< info >}}Replace `<YOUR_EMAIL_DOMAIN>` with your organization's email domain. <br /><br />**Note**: Specify only a single email domain for the `<YOUR_EMAIL_DOMAIN>` parameter — no comma-separated list or array of domains is allowed.{{< /info >}} |
| Relay State |  - |

3. Click the meatballs menu (`...`) to the right of **Attributes & Claims** and remove any **Additional claims**. Then, click **Add new claim** and enter the following information:

| Field | Value | Notes |
| :---| :---| :---|
| Email | `user.mail` | - |
| LastName | `user.displayname` | Choose your preferred name, for example, display name or surname. | 
| Unique User Identifier | `user.userprincipalname` | - |

4. Copy the **App Federation Metadata URL**.

{{< image src="images/user-guides/azure-sso/rudderstack-azure-sso-8.webp" alt="Metadata URL" >}}

{{< warning >}}
Before sharing the App Federation Metadata URL, verify that the IdP metadata declares both HTTP-Redirect and HTTP-POST SAML bindings. 

RudderStack uses AWS Cognito, which sends the initial login request with HTTP-Redirect, so metadata that advertises only HTTP-POST will be rejected.
{{< /warning >}}

5. Share the **App Federation Metadata URL** with the [RudderStack team](mailto:support@rudderstack.com).

{{< info >}}
While sharing the metadata URL, also let the RudderStack team know:

- Which workspace you would like to set as the **default workspace** for your organization. New users who sign in through SSO for the first time will automatically land in this workspace.
- Whether you want RudderStack to also create a **personal organization** for each new SSO user. This is **off by default**.

You can also opt out of setting up a default workspace altogether if you don't want your SSO users to get automatic access to a shared workspace.
{{< /info >}}

## Step 3: Set up SCIM

This section lists the steps to set up SCIM provisioning in Azure Entra ID.

### Prerequisites

Before setting up SCIM provisioning,  make sure to generate an [organization-level Service Access Token]({{< ref "access-management/service-access-tokens.md#organization-sat" >}}) in the RudderStack workspace for which you want to enable SCIM.

{{< warning >}}
Make sure to create an **organization-level** Service Access Token. Otherwise, your SCIM provisioning tasks will fail.
{{< /warning >}}

#### Token permissions for legacy RBAC system

If you are on the [legacy Permissions Management (RBAC) system]({{< ref "archive/dashboard-guides/user-management.md" >}}), generate an [Organization-level Service Access Token]({{< ref "archive/dashboard-guides/service-access-tokens.md#generate-service-access-token" >}}).

### SCIM configuration

1. In the left sidebar of your app, go to **Manage** > **Provisioning** > **Get started**.

{{< image src="images/user-guides/azure-sso/rudderstack-azure-sso-9.webp" alt="Provisioning" >}}

2. Under **Provisioning Mode**, choose **Automatic** and enter the following credentials:

| Field | Value | 
| :---| :---| 
| Tenant URL <br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `https://api.rudderstack.com/scim/v2` |
| Secret Token | Your Service Access Token obtained in the [Prerequisites](#prerequisites) section. |

{{< image src="images/user-guides/azure-sso/rudderstack-azure-sso-10.webp" alt="Provisioning" >}}

3. Click **Test Connection** - it should be successful.

{{< announcement >}}
If you see a `403 - Forbidden` error, contact the [RudderStack team](mailto:support@rudderstack.com) to enable SCIM for your organization.
{{< /announcement >}}

## Enable SSO login

RudderStack does not support IdP-initiated authentication. Make sure the users log in through `https://app.rudderstack.com/sso`.

## Known issues

RudderStack does not support the following SCIM features currently:

- Import users
- Import groups
- Push groups (coming soon)
- Remove users
- Sync password
- Enhanced group push

{{< warning >}}
RudderStack does not support removing users - this is because it uses SCIM with SAML, where removing a user from Azure Entra ID implies that they also lose the ability to authenticate to RudderStack completely (logins via passwords, Google, etc. are completely blocked). 

Instead, RudderStack supports deactivating the user which means they only lose access to the organization.
{{< /warning >}}

## Debugging

{{< customreadfile "/includes/sso-debugging.md" >}}

#### Invalid samlResponse or relayState from identity provider

{{< image src="images/user-guides/sso-errors-1.webp" alt="SSO errors" >}}

The above error indicates you tried the [IdP](https://support.okta.com/help/s/article/okta-saml?language=en_US)-initiated authentication flow. As stated above, this integration supports only [Service Provider (SP)-initiated SSO flow](#supported-features).

RudderStack recommends initiating the SSO authentication by following all the above SSO configuration steps correctly and making sure the users log in through `https://app.rudderstack.com/sso`.

#### Required String parameter 'RelayState' is not present

{{< image src="images/user-guides/sso-errors-2.webp" alt="SSO errors" >}}

The above error indicates that you did not set up your SSO app correctly. Make sure to:

- Set the **Identifier (Entity ID)** field to `urn:amazon:cognito:sp:us-east-1_ABZiTjXia`.
- Under **Attributes & Claims**, set the **Email** field to `user.email`.
- Configure the other [SAML settings](#step-2-set-up-saml) correctly.

## FAQ

{{< customreadfile "/includes/sso-faq.md" >}}