# Integrate with Microsoft Entra ID

This guide connects an AISIX Enterprise or AISIX Cloud organization to Microsoft Entra ID through SAML single sign-on (SSO). When you finish, the people you assign to an Entra ID enterprise application sign in to the dashboard with their Entra ID account, and the Entra ID app role you give them sets their role in the organization.

The steps follow the order an administrator works in, switching between the Microsoft Entra admin center and the dashboard. How SSO behaves once it is configured, including membership, role mapping, enforcement, and sessions, is described in [Single Sign-On (SAML)](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md).

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before you start, make sure you have:

* The **owner** role in the organization. Only owners can change the SSO connection.
* A Microsoft Entra ID role that can create and configure enterprise applications, such as Cloud Application Administrator or Application Administrator.
* An AISIX Enterprise or AISIX Cloud control plane that browsers reach over HTTPS at its public base URL. In AISIX Enterprise, this is `AISIX_CLOUD_PUBLIC_BASE_URL`, or `api.publicBaseURL` in the Helm chart. See [Runtime URLs](https://docs.api7.ai/ai-gateway/reference/on-premises-configuration.md#runtime-urls).

Entra ID accepts an `http://` reply URL only for `localhost`, and the My Apps tile does not open an `http://` sign-on URL at all, so a plain HTTP control plane is suitable only for local testing.

## Create the Enterprise Application[​](#create-the-enterprise-application "Direct link to Create the Enterprise Application")

Create a non-gallery enterprise application for the control plane:

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com) and browse to **Entra ID** > **Enterprise apps** > **All applications**.
2. Select **New application**, then **Create your own application**.
3. Enter a name, such as `AISIX`, select the option to integrate an application that is not in the gallery (**Non-gallery**), and select **Create**.
4. In the new application, under **Manage**, select **Single sign-on**, then **SAML**.

The **Set up Single Sign-On with SAML** page opens. Keep it open for the next steps.

## Copy the Service Provider Values[​](#copy-the-service-provider-values "Direct link to Copy the Service Provider Values")

In the dashboard, open **Settings**, select the **Authentication** tab, and find the **Single sign-on (SAML)** card. Its **Service provider** section shows three values, each with a **Copy** button:

* **Entity ID (Identifier)**: `<public-base-url>/api/auth/sso/saml/<org-id>/metadata`
* **Assertion Consumer Service URL (Reply URL)**: `<public-base-url>/api/auth/sso/saml/<org-id>/acs`
* **Sign-on URL**: `<public-base-url>/login?sso=<org-slug>`

The card shows these values before any connection is saved, so you can register the application in Entra ID first. For how the values are built, see [Service Provider Values](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#service-provider-values).

## Enter the Basic SAML Configuration[​](#enter-the-basic-saml-configuration "Direct link to Enter the Basic SAML Configuration")

On the **Set up Single Sign-On with SAML** page in Entra ID, select **Edit** in the **Basic SAML Configuration** section and enter the values from the SSO card:

| Entra ID field                                 | Value from the SSO card                        |
| ---------------------------------------------- | ---------------------------------------------- |
| **Identifier (Entity ID)**                     | **Entity ID (Identifier)**                     |
| **Reply URL (Assertion Consumer Service URL)** | **Assertion Consumer Service URL (Reply URL)** |
| **Sign on URL**                                | **Sign-on URL**                                |

Leave the relay state and the logout URL empty, and select **Save**.

Do not skip the **Sign on URL**. The control plane accepts only sign-ins that it started itself. With the sign-on URL set, the application's tile in My Apps opens the dashboard sign-in page, which starts the sign-in. Without it, the tile makes Entra ID send a response that the control plane did not ask for, and the control plane refuses it with `SSO_UNSOLICITED_RESPONSE`.

## Check the Attributes and Claims[​](#check-the-attributes-and-claims "Direct link to Check the Attributes and Claims")

The control plane reads three values from the SAML assertion:

* **Name identifier (NameID)**, which identifies the person. After the first sign-in, the control plane recognizes the person by it alone, so it must not change when the person's email address or user name does. See [Identity Links](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#identity-links).
* **Email address**, from the `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` claim. When that claim is absent, the control plane uses the NameID instead if it has the form of an email address. The address is what a first sign-in is matched by, where the control plane trusts the IdP for it. See [First Sign-In](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#first-sign-in).
* **Display name**, from the `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` claim, or the `givenname` and `surname` claims joined when it is absent. The control plane sets the account's name from the display name when it creates the account, and in AISIX Cloud when the sign-in [takes over](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#first-sign-in) an account that was registered for the address but never verified. An account that already verified its address keeps its name, and later sign-ins do not change it.

In the **Attributes & Claims** section, check that the application has the default claims:

| Claim                                                                | Source attribute         |
| -------------------------------------------------------------------- | ------------------------ |
| **Unique User Identifier (Name ID)**                                 | `user.userprincipalname` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `user.mail`              |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`         | `user.userprincipalname` |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname`    | `user.givenname`         |
| `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname`      | `user.surname`           |

If the list of claims is empty, add these claims before you continue. An application that was created with Microsoft Graph, PowerShell, or an infrastructure-as-code tool, rather than in the admin center, often has no claims configuration. Entra ID then sends an opaque pairwise identifier as the NameID and no `emailaddress` claim, so the control plane receives no email address.

Then change the NameID to the user's object ID, which never changes:

1. Select the **Unique User Identifier (Name ID)** claim.
2. Set **Name identifier format** to **Persistent**, and **Source attribute** to `user.objectid`.
3. Select **Save**.

The default NameID, the user principal name (UPN), also works, but it changes when a user is renamed. A renamed user is then refused with `SSO_ACCOUNT_ALREADY_LINKED` until they are removed from the organization and added back. Make this change before people start signing in: changing the NameID later has the same effect on everyone who has already signed in. See [Changing the NameID Later](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#changing-the-nameid-later).

With the object ID as the NameID, the email address comes only from the `emailaddress` claim, `user.mail`, which Entra ID omits for a user who has no `mail` value. Such a user can still sign in, but the control plane gets no email address for them, so their first sign-in always goes to the [Connect page](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#the-connect-page), where only an existing account can be connected. To use the UPN as the address instead, set **Email attribute** on the SSO card to `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`, which carries the UPN.

To show people's names in the dashboard instead of their UPN, change the source attribute of the `name` claim to `user.displayname`.

Do not turn on token encryption for the application. The control plane does not accept encrypted assertions. Entra ID signs the assertion with RSA-SHA256 and leaves the response unsigned, which the control plane accepts.

If you also provision users from Entra ID through [SCIM](https://docs.api7.ai/ai-gateway/cloud/scim-directory-sync.md), a user it provisions at an address outside the organization's verified domains joins when they connect SSO with a NameID equal to the `externalId` that SCIM sent. Map the same Entra ID attribute to both, such as `objectId` to `externalId` in the provisioning attribute mappings when the NameID is `user.objectid`. See [Members Waiting to Join](https://docs.api7.ai/ai-gateway/cloud/scim-directory-sync.md#members-waiting-to-join).

## Define App Roles[​](#define-app-roles "Direct link to Define App Roles")

App roles let Entra ID tell the control plane which role each person should have. Define one app role for each organization role that differs from the connection's default role. For example, an app role for admins:

1. In the Microsoft Entra admin center, browse to **Entra ID** > **App registrations**, select **All applications**, and select the application you created. It has the same name as the enterprise application.
2. Under **Manage**, select **App roles**, then **Create app role**.
3. Enter a **Display name**, such as `AISIX Admin`, set **Allowed member types** to **Users/Groups**, enter a **Value**, such as `AISIX.Admin`, and enter a **Description**.
4. Keep **Do you want to enable this app role?** selected, and select **Apply**.

The **Value** is what Entra ID sends in the `http://schemas.microsoft.com/ws/2008/06/identity/claims/role` claim, and what the role mapping rule compares, including case.

People who have no app role, or an app role that no rule matches, get the connection's default role. You do not need an app role for them.

### Use Groups Instead of App Roles[​](#use-groups-instead-of-app-roles "Direct link to Use Groups Instead of App Roles")

App roles are the recommended choice, but rules can also read Entra ID groups. Under **Attributes & Claims**, select **Add a group claim**. Entra ID then sends the `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` claim, whose values are group object IDs by default, so a rule's value is the object ID of the group, not its name.

Entra ID sends at most 150 groups in a SAML assertion and omits the claim entirely for a user in more groups. Choose **Groups assigned to the application** to send only the groups assigned to the application, which keeps the claim small.

## Assign Users and Groups[​](#assign-users-and-groups "Direct link to Assign Users and Groups")

Entra ID signs in only the users assigned to the application when its **Assignment required?** property is **Yes**, which you can check under **Manage** > **Properties**. To assign people:

1. In the enterprise application, under **Manage**, select **Users and groups**, then **Add user/group**.
2. Under **Users and groups**, select the users or groups who should be able to sign in, and choose **Select**.
3. Under **Select a role**, choose the app role for them, such as `AISIX Admin`, and choose **Select**. Skip this step for people who should get the default role.
4. Select **Assign**.

Assigning a group requires Microsoft Entra ID P1 or P2, and the assignment covers only the group's direct members.

A change of app role takes effect at the person's next sign-in through the dashboard.

## Download the Federation Metadata[​](#download-the-federation-metadata "Direct link to Download the Federation Metadata")

In the **SAML Certificates** section of the **Set up Single Sign-On with SAML** page, select **Download** next to **Federation Metadata XML**.

The file describes Entra ID as the identity provider: its entity ID, its sign-in URL, and its signing certificate.

## Configure the Connection in the Dashboard[​](#configure-the-connection-in-the-dashboard "Direct link to Configure the Connection in the Dashboard")

In the dashboard, open **Settings** > **Authentication** > **Single sign-on (SAML)** and complete the connection:

1. Paste the metadata into **Identity provider metadata XML** and select **Read metadata**, or select **Upload metadata file** and choose the downloaded file.

2. Check the fields that the metadata filled in:

   * **Identity provider entity ID**: `https://sts.windows.net/<tenant-id>/`
   * **Single sign-on URL**: `https://login.microsoftonline.com/<tenant-id>/saml2`
   * **Signing certificates**: one certificate. The metadata repeats the certificate in several places, and the control plane keeps one copy.

3. Turn on **Enable single sign-on**.

4. Turn on **Add new members on sign-in (just-in-time)** if people who are not members yet should join on their first sign-in. Otherwise, invite them first, or provision them through [SCIM](https://docs.api7.ai/ai-gateway/cloud/scim-directory-sync.md).

5. Keep **Default role** at **Restricted Member**, or choose the role that people without a matching app role should get.

6. Under **Role mapping**, select **Add rule** and enter the rule for the admin app role:

   | Attribute                                                      | Operator             | Value         | Role      |
   | -------------------------------------------------------------- | -------------------- | ------------- | --------- |
   | `http://schemas.microsoft.com/ws/2008/06/identity/claims/role` | **any value equals** | `AISIX.Admin` | **Admin** |

7. Leave **Email attribute** and **Display name attribute** empty to use the defaults.

8. Select **Save**.

With a role mapping rule in place, the control plane sets the role that SSO assigned at every sign-in, so a member who loses the `AISIX.Admin` app role loses **Admin** at their next sign-in. Roles assigned by hand or held through teams are not changed, and neither are owners. See [Map IdP Attributes to Roles](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#map-idp-attributes-to-roles).

You can also skip the metadata and enter the three fields by hand. On the **Set up Single Sign-On with SAML** page in Entra ID, they are **Microsoft Entra Identifier** and **Login URL** in the section that sets up the application, and the **Certificate (Base64)** download in **SAML Certificates**.

## Test the Sign-In[​](#test-the-sign-in "Direct link to Test the Sign-In")

Test with a user who is assigned to the application, in a private browser window:

1. Open the sign-on URL, `<public-base-url>/login?sso=<org-slug>`.
2. Select **Sign in with SSO**.
3. Sign in to Microsoft with the user's account.

The browser returns to the dashboard. In AISIX Enterprise, or in AISIX Cloud when the user's email address is on one of the organization's [verified domains](https://docs.api7.ai/ai-gateway/cloud/organization-domains.md), it opens the organization. Otherwise, in AISIX Cloud, the first sign-in opens the [Connect page](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#the-connect-page), where the user connects an account and confirms. Later sign-ins open the organization directly. On the **Members** page, check that the member has the role their app role maps to.

Members can also start from the regular sign-in page, `<public-base-url>/login`. In AISIX Enterprise, it shows a **Continue with `<organization>` SSO** button that goes straight to Entra ID. In AISIX Cloud, the member selects **Continue with SSO** and enters the organization's identifier, the `<org-slug>` in the sign-on URL. See [SSO Sign-In](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#sso-sign-in).

Multi-factor authentication, including Microsoft security defaults and Conditional Access, happens in Entra ID before the control plane receives the response. There is nothing to configure for it in the control plane. A test user without a registered authentication method may first be asked by Microsoft to register one.

### Sign In from My Apps[​](#sign-in-from-my-apps "Direct link to Sign In from My Apps")

Assigned users also see the application as a tile in [My Apps](https://myapps.microsoft.com). Selecting the tile opens the dashboard sign-on URL, where the user selects **Sign in with SSO** once more. Entra ID already has the user's session, so the sign-in then completes without another prompt.

The tile works only with an HTTPS **Sign on URL**. With an `http://` sign-on URL, even on `localhost`, My Apps reports **App launch failed**. With no sign-on URL, the control plane refuses the sign-in with `SSO_UNSOLICITED_RESPONSE`.

## Require Single Sign-On[​](#require-single-sign-on "Direct link to Require Single Sign-On")

After a test sign-in succeeds, you can make SSO the only way for members other than owners to reach the organization. On the SSO card, turn on **Require single sign-on** and select **Save**. Owners can still sign in with their password, which keeps a way in if Entra ID is unavailable or misconfigured. See [Require Single Sign-On](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#require-single-sign-on).

## Rotate the Signing Certificate[​](#rotate-the-signing-certificate "Direct link to Rotate the Signing Certificate")

Entra ID creates the application's signing certificate with a validity of three years and emails the notification addresses on the **SAML Signing Certificate** page before it expires. An SSO connection holds up to 10 certificates and accepts a response signed by any of them, so you can rotate without an outage.

Before rotating the certificate, note whether **Require single sign-on** is enabled. Changing the certificate list turns it off.

Use this sequence:

1. In Entra ID, in the **SAML Certificates** section, select **Edit**. On the **SAML Signing Certificate** page, select **New Certificate**, then **Save**. The new certificate is **Inactive**.
2. Select the ellipsis (**...**) next to the new certificate and download it in Base64 format.
3. On the dashboard SSO card, select **Add certificate**, paste the certificate, and select **Save**. Alternatively, download the **Federation Metadata XML** again, which now lists both certificates, and read it with **Read metadata**.
4. In Entra ID, select the ellipsis (**...**) next to the new certificate and select **Make certificate active**.
5. Sign in through SSO to confirm that sign-in works with the new certificate.
6. Remove the old certificate from the SSO card and select **Save**.
7. If **Require single sign-on** was enabled before the rotation, turn it back on and select **Save**.

Any change to the certificates on the SSO card, adding or removing, turns **Require single sign-on** off, because the new settings have not been proven by a sign-in yet. Restore the previous enforcement setting only after the new certificate works.

If Entra ID signs with a certificate that the SSO card does not hold, for example because the new certificate was made active before it was added to the control plane, every sign-in fails with `SSO_RESPONSE_INVALID`.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

Errors from Entra ID appear on a Microsoft page after the user enters their credentials. Errors from the control plane send the browser back to the dashboard sign-in page with an explanation. The full list of SSO error codes is in [Troubleshooting](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#troubleshooting).

| Symptom                                                                                                                                                         | Cause                                                                                                                                                                 | Fix                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AADSTS50011: The reply URL ... does not match the reply URLs configured for the application`                                                                   | The **Reply URL** in Entra ID differs from the SSO card's reply URL, often because the control plane's public base URL changed after the application was registered.  | Copy **Assertion Consumer Service URL (Reply URL)** from the SSO card into the **Basic SAML Configuration** again.                                                                                                                                                                       |
| `AADSTS50105: Your administrator has configured the application ... to block users unless they are specifically granted ('assigned') access to the application` | The user is not assigned to the application, directly or through a group.                                                                                             | Assign the user or one of their groups under **Users and groups**.                                                                                                                                                                                                                       |
| **App launch failed** in My Apps                                                                                                                                | The **Sign on URL** is an `http://` URL.                                                                                                                              | Use the HTTPS sign-on URL of the control plane.                                                                                                                                                                                                                                          |
| Every first sign-in opens the Connect page without an email address                                                                                             | The application has no claims configuration, so Entra ID sends a pairwise NameID and no `emailaddress` claim. Or the user has no `mail` value.                        | Add the default claims in **Attributes & Claims**, as in [Check the Attributes and Claims](#check-the-attributes-and-claims). Alternatively, set **Email attribute** on the SSO card to `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`, which Entra ID fills with the UPN. |
| `SSO_ACCOUNT_ALREADY_LINKED`                                                                                                                                    | The user's NameID changed since their first sign-in: the user was renamed while the NameID is the UPN, or the **Unique User Identifier (Name ID)** claim was changed. | Remove the user from the organization and add them back. To avoid it, use `user.objectid` as the NameID.                                                                                                                                                                                 |
| `SSO_UNSOLICITED_RESPONSE`                                                                                                                                      | The sign-in started in Entra ID, for example from My Apps without a **Sign on URL**.                                                                                  | Set the **Sign on URL** in the **Basic SAML Configuration**, and start sign-ins from the dashboard.                                                                                                                                                                                      |
| `SSO_RESPONSE_INVALID`                                                                                                                                          | Entra ID signed the response with a certificate that the SSO card does not hold.                                                                                      | Add the active certificate to the SSO card, or read the current federation metadata again.                                                                                                                                                                                               |
| `SSO_ENCRYPTED_ASSERTION_UNSUPPORTED`                                                                                                                           | Token encryption is on for the application.                                                                                                                           | Turn off token encryption in Entra ID.                                                                                                                                                                                                                                                   |
| `SSO_NOT_A_MEMBER`                                                                                                                                              | The person is assigned in Entra ID but is not a member of the organization, and just-in-time provisioning is off.                                                     | Invite the person, provision them through SCIM, or turn on **Add new members on sign-in (just-in-time)**.                                                                                                                                                                                |

## Next Steps[​](#next-steps "Direct link to Next Steps")

Use [SCIM Directory Sync](https://docs.api7.ai/ai-gateway/cloud/scim-directory-sync.md) to provision and deprovision members from Entra ID ahead of their first sign-in, and [Roles and Permissions](https://docs.api7.ai/ai-gateway/cloud/custom-roles.md) to define the roles that the role mapping rules can assign.
