# 集成 Microsoft Entra ID

本指南通过 SAML 单点登录（SSO）把 AISIX Enterprise 或 AISIX Cloud 组织与 Microsoft Entra ID 连接起来。完成后，分配到 Entra ID 企业应用的人员可以用其 Entra ID 账号登录控制台，并由你为其分配的 Entra ID 应用角色决定其在组织中的角色。

以下步骤按管理员实际操作的顺序排列，在 Microsoft Entra 管理中心与控制台之间来回切换。配置完成后 SSO 的行为（包括成员加入、角色映射、强制单点登录和会话）请参见[单点登录（SAML）](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md)。

## 前提条件[​](#prerequisites "前提条件的直接链接")

开始之前，请确认：

* 你拥有组织的 **所有者** 角色。只有所有者可以修改 SSO 连接。
* 你在 Microsoft Entra ID 中拥有可创建和配置企业应用的角色，例如 Cloud Application Administrator 或 Application Administrator。
* 浏览器能通过 HTTPS 访问 AISIX Enterprise 或 AISIX Cloud 控制面的公开 URL。在 AISIX Enterprise 中，该地址即 `AISIX_CLOUD_PUBLIC_BASE_URL`，在 Helm Chart 中为 `api.publicBaseURL`。参见[运行时 URL](https://docs.apiseven.com/ai-gateway/reference/on-premises-configuration.md#runtime-urls)。

Entra ID 只对 `localhost` 接受 `http://` 回复 URL，而 My Apps 磁贴完全无法打开 `http://` 登录 URL，因此纯 HTTP 的控制面只适合本地测试。

## 创建企业应用[​](#create-the-enterprise-application "创建企业应用的直接链接")

为控制面创建一个非库应用：

1. 登录 [Microsoft Entra 管理中心](https://entra.microsoft.com)，进入 **Entra ID** > **Enterprise apps** > **All applications**。
2. 选择 **New application**，然后选择 **Create your own application**。
3. 输入名称（例如 `AISIX`），选择 **Integrate any other application you don't find in the gallery (Non-gallery)**，然后选择 **Create**。
4. 在新应用的 **Manage** 下选择 **Single sign-on**，再选择 **SAML**。

随后会打开 **Set up Single Sign-On with SAML** 页面，后续步骤都在这个页面上进行。

## 复制服务提供方信息[​](#copy-the-service-provider-values "复制服务提供方信息的直接链接")

在控制台中打开 **设置**，选择 **身份认证** 标签页，找到 **单点登录（SAML）** 卡片。其中 **服务提供商** 部分列出三项值，每项都带有 **复制** 按钮：

* **实体 ID（标识符）**：`<public-base-url>/api/auth/sso/saml/<org-id>/metadata`
* **断言消费服务 URL（回复 URL）**：`<public-base-url>/api/auth/sso/saml/<org-id>/acs`
* **登录 URL**：`<public-base-url>/login?sso=<org-slug>`

在保存任何连接之前，卡片上就已显示这些值，因此可以先在 Entra ID 中完成应用登记。这些值的生成方式参见[服务提供方信息](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#service-provider-values)。

## 填写基本 SAML 配置[​](#enter-the-basic-saml-configuration "填写基本 SAML 配置的直接链接")

在 Entra ID 的 **Set up Single Sign-On with SAML** 页面上，在 **Basic SAML Configuration** 部分选择 **Edit**，填写 SSO 卡片中的值：

| Entra ID 字段                                  | SSO 卡片中的值                   |
| ---------------------------------------------- | -------------------------------- |
| **Identifier (Entity ID)**                     | **实体 ID（标识符）**            |
| **Reply URL (Assertion Consumer Service URL)** | **断言消费服务 URL（回复 URL）** |
| **Sign on URL**                                | **登录 URL**                     |

Relay State 和登出 URL 保持为空，然后选择 **Save**。

请务必填写 **Sign on URL**。控制面只接受由它自己发起的登录。填写登录 URL 后，My Apps 中的应用磁贴会打开控制台登录页面，由该页面发起登录。如果不填写，点击磁贴会让 Entra ID 发送一个控制面并未请求的响应，控制面会以 `SSO_UNSOLICITED_RESPONSE` 拒绝它。

## 检查属性和声明[​](#check-the-attributes-and-claims "检查属性和声明的直接链接")

控制面从 SAML 断言中读取三项值：

* **名称标识符（NameID）**，用于识别此人。首次登录之后，控制面只按它识别此人，因此它不能随此人的邮箱地址或用户名变化。参见[身份关联](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#identity-links)。
* **邮箱地址**，取自 `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` 声明。该声明不存在时，如果 NameID 是邮箱格式，控制面会改用它。在控制面信任身份提供方断言该地址的情况下，首次登录按这个地址匹配账号。参见[首次登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#first-sign-in)。
* **显示名称**，取自 `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` 声明；该声明不存在时，拼接 `givenname` 和 `surname` 声明。控制面在创建账号时，以及在 AISIX Cloud 中登录[接管](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#first-sign-in)一个为该地址注册却从未验证邮箱的账号时，用显示名称设置账号名称。已验证过邮箱的账号保留原名称，之后的登录也不会修改它。

在 **Attributes & Claims** 部分，确认应用带有以下默认声明：

| 声明                                                                 | 源属性                   |
| -------------------------------------------------------------------- | ------------------------ |
| **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`           |

如果声明列表为空，请先添加这些声明再继续。通过 Microsoft Graph、PowerShell 或基础设施即代码工具（而不是在管理中心中）创建的应用，常常没有任何声明配置。此时 Entra ID 会把一个不透明的成对标识符作为 NameID 发送，并且不发送 `emailaddress` 声明，控制面因此收不到邮箱地址。

然后把 NameID 改为永不变化的用户对象 ID：

1. 选择 **Unique User Identifier (Name ID)** 声明。
2. 将 **Name identifier format** 设为 **Persistent**，**Source attribute** 设为 `user.objectid`。
3. 选择 **Save**。

默认的 NameID，即用户主体名称（UPN），也可以使用，但用户改名时 UPN 会变化。改名后的用户会被拒绝并返回 `SSO_ACCOUNT_ALREADY_LINKED`，直到被移出组织再重新加入。请在成员开始登录之前完成这项修改：之后再改 NameID，对所有已经登录过的人都会产生同样的影响。参见[之后更改 NameID](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#changing-the-nameid-later)。

使用对象 ID 作为 NameID 时，邮箱地址只来自 `emailaddress` 声明，即 `user.mail`；用户没有 `mail` 值时，Entra ID 不会发送该声明。这样的用户仍可登录，但控制面收不到其邮箱地址，因此首次登录总会进入[关联页面](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#the-connect-page)，且只能关联已有账号。如果想改用 UPN 作为邮箱地址，请把 SSO 卡片上的 **邮箱属性** 设为携带 UPN 的 `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`。

如果希望控制台显示人员姓名而不是 UPN，请把 `name` 声明的源属性改为 `user.displayname`。

不要为该应用开启 Token 加密，控制面不接受加密的断言。Entra ID 使用 RSA-SHA256 对断言签名，不对响应签名，控制面接受这种方式。

如果同时通过 [SCIM](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md) 从 Entra ID 预配用户，那么地址在组织已验证域名以外的用户，会在以等于 SCIM 所发送 `externalId` 的 NameID 关联 SSO 时加入。请把同一个 Entra ID 属性同时映射到两者，例如 NameID 为 `user.objectid` 时，在预配的属性映射中把 `objectId` 映射到 `externalId`。参见[等待加入的成员](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md#members-waiting-to-join)。

## 定义应用角色[​](#define-app-roles "定义应用角色的直接链接")

应用角色用来让 Entra ID 告诉控制面每个人应具有的角色。请为每个不同于连接默认角色的组织角色定义一个应用角色。以管理员的应用角色为例：

1. 在 Microsoft Entra 管理中心进入 **Entra ID** > **App registrations**，选择 **All applications**，然后选择你创建的应用。它与企业应用同名。
2. 在 **Manage** 下选择 **App roles**，然后选择 **Create app role**。
3. 输入 **Display name**（例如 `AISIX Admin`），将 **Allowed member types** 设为 **Users/Groups**，输入 **Value**（例如 `AISIX.Admin`），并填写 **Description**。
4. 保持勾选 **Do you want to enable this app role?**，然后选择 **Apply**。

**Value** 就是 Entra ID 在 `http://schemas.microsoft.com/ws/2008/06/identity/claims/role` 声明中发送的值，也是角色映射规则比较的值，区分大小写。

没有应用角色、或其应用角色没有被任何规则命中的人，会获得连接的默认角色，无需为他们定义应用角色。

### 使用组代替应用角色[​](#use-groups-instead-of-app-roles "使用组代替应用角色的直接链接")

推荐使用应用角色，但规则也可以读取 Entra ID 组。在 **Attributes & Claims** 中选择 **Add a group claim**。Entra ID 随后会发送 `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` 声明，其值默认是组的对象 ID，因此规则的值应填组的对象 ID，而不是组名。

Entra ID 在 SAML 断言中最多发送 150 个组，用户所属组超过该数量时会完全省略该声明。选择 **Groups assigned to the application** 可以只发送分配给该应用的组，使声明保持精简。

## 分配用户和组[​](#assign-users-and-groups "分配用户和组的直接链接")

应用的 **Assignment required?** 属性为 **Yes** 时，Entra ID 只允许已分配到该应用的用户登录。可以在 **Manage** > **Properties** 中查看该属性。分配人员的步骤如下：

1. 在企业应用的 **Manage** 下选择 **Users and groups**，然后选择 **Add user/group**。
2. 在 **Users and groups** 中选择应能登录的用户或组，然后选择 **Select**。
3. 在 **Select a role** 中为其选择应用角色（例如 `AISIX Admin`），然后选择 **Select**。应获得默认角色的人员可跳过此步。
4. 选择 **Assign**。

分配组需要 Microsoft Entra ID P1 或 P2，且分配只覆盖组的直接成员。

应用角色的变更会在该人员下次通过控制台登录时生效。

## 下载联合元数据[​](#download-the-federation-metadata "下载联合元数据的直接链接")

在 **Set up Single Sign-On with SAML** 页面的 **SAML Certificates** 部分，选择 **Federation Metadata XML** 旁的 **Download**。

该文件描述了作为身份提供方的 Entra ID：它的实体 ID、登录 URL 和签名证书。

## 在控制台中配置连接[​](#configure-the-connection-in-the-dashboard "在控制台中配置连接的直接链接")

在控制台中打开 **设置** > **身份认证** > **单点登录（SAML）**，完成连接配置：

1. 将元数据粘贴到 **身份提供商元数据 XML** 中并选择 **读取元数据**，或选择 **上传元数据文件** 并选择下载的文件。

2. 检查元数据填写的字段：

   * **身份提供商实体 ID**：`https://sts.windows.net/<tenant-id>/`
   * **单点登录 URL**：`https://login.microsoftonline.com/<tenant-id>/saml2`
   * **签名证书**：一个证书。元数据会在多处重复同一证书，控制面只保留一份。

3. 开启 **启用单点登录**。

4. 如果希望尚不是成员的人在首次登录时加入组织，开启 **登录时自动添加新成员（JIT）**；否则请先邀请他们，或通过 [SCIM](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md) 预配。

5. **默认角色** 保持为 **受限成员**，或选择没有命中应用角色的人员应获得的角色。

6. 在 **角色映射** 下选择 **添加规则**，为管理员应用角色填写规则：

   | 属性                                                           | 运算符         | 值            | 角色       |
   | -------------------------------------------------------------- | -------------- | ------------- | ---------- |
   | `http://schemas.microsoft.com/ws/2008/06/identity/claims/role` | **任一值等于** | `AISIX.Admin` | **管理员** |

7. **邮箱属性** 和 **显示名称属性** 留空，使用默认值。

8. 选择 **保存**。

存在角色映射规则时，控制面会在每次登录时重新设置 SSO 分配的角色，因此失去 `AISIX.Admin` 应用角色的成员会在下次登录时失去 **管理员**。手动分配的角色和通过团队持有的角色不受影响，所有者也不会被修改。参见[将身份提供方属性映射为角色](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#map-idp-attributes-to-roles)。

也可以不用元数据，手动填写这三个字段。在 Entra ID 的 **Set up Single Sign-On with SAML** 页面上，它们分别是设置应用部分中的 **Microsoft Entra Identifier** 和 **Login URL**，以及 **SAML Certificates** 中的 **Certificate (Base64)** 下载项。

## 测试登录[​](#test-the-sign-in "测试登录的直接链接")

在浏览器隐私窗口中，用一个已分配到该应用的用户测试：

1. 打开登录 URL `<public-base-url>/login?sso=<org-slug>`。
2. 选择 **使用 SSO 登录**。
3. 用该用户的账号登录 Microsoft。

浏览器会回到控制台。在 AISIX Enterprise 中，或在 AISIX Cloud 中且用户的邮箱地址位于组织的某个[已验证域名](https://docs.apiseven.com/ai-gateway/cloud/organization-domains.md)内时，会直接进入该组织。否则在 AISIX Cloud 中，首次登录会进入[关联页面](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#the-connect-page)，用户在此关联账号并确认；之后的登录直接进入组织。在 **成员** 页面上，确认该成员的角色与其应用角色映射的角色一致。

成员也可以从常规登录页面 `<public-base-url>/login` 开始登录。在 AISIX Enterprise 中，该页面会显示 **使用 `<组织>` 的 SSO 登录** 按钮，点击后直接跳转到 Entra ID。在 AISIX Cloud 中，成员选择 **使用 SSO 登录**，再输入组织标识，即登录 URL 中的 `<org-slug>`。参见[通过 SSO 登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#sso-sign-in)。

多重身份验证（包括 Microsoft 安全默认值和条件访问）在控制面收到响应之前就已在 Entra ID 中完成，控制面中无需为此做任何配置。尚未注册验证方式的测试用户可能会先被 Microsoft 要求注册一种验证方式。

### 从 My Apps 登录[​](#sign-in-from-my-apps "从 My Apps 登录的直接链接")

已分配的用户还会在 [My Apps](https://myapps.microsoft.com) 中看到该应用的磁贴。点击磁贴会打开控制台的登录 URL，用户需要在该页面上再选择一次 **使用 SSO 登录**。由于 Entra ID 已有该用户的会话，之后的登录无需再次输入凭据即可完成。

磁贴只适用于 HTTPS 的 **Sign on URL**。如果登录 URL 是 `http://`（即使是 `localhost`），My Apps 会报告 **App launch failed**。如果没有填写登录 URL，控制面会以 `SSO_UNSOLICITED_RESPONSE` 拒绝登录。

## 强制单点登录[​](#require-single-sign-on "强制单点登录的直接链接")

测试登录成功后，可以让 SSO 成为所有者以外的成员访问组织的唯一方式。在 SSO 卡片上开启 **强制单点登录**，然后选择 **保存**。所有者仍可用密码登录，从而在 Entra ID 不可用或配置错误时保留进入组织的途径。参见[强制单点登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#require-single-sign-on)。

## 轮换签名证书[​](#rotate-the-signing-certificate "轮换签名证书的直接链接")

Entra ID 为应用创建的签名证书有效期为三年，并会在证书到期前向 **SAML Signing Certificate** 页面上的通知邮箱发送提醒。一个 SSO 连接最多保存 10 个证书，由其中任一证书签名的响应都会被接受，因此可以在不中断登录的情况下轮换。

轮换证书前，请记录是否已启用 **强制单点登录**。修改证书列表会将其关闭。

按以下顺序操作：

1. 在 Entra ID 的 **SAML Certificates** 部分选择 **Edit**。在 **SAML Signing Certificate** 页面上选择 **New Certificate**，然后选择 **Save**。新证书的状态为 **Inactive**。
2. 选择新证书旁的省略号（**...**），以 Base64 格式下载该证书。
3. 在控制台的 SSO 卡片上选择 **添加证书**，粘贴证书后选择 **保存**。也可以重新下载 **Federation Metadata XML**（其中已同时包含新旧两个证书），再用 **读取元数据** 导入。
4. 在 Entra ID 中选择新证书旁的省略号（**...**），选择 **Make certificate active**。
5. 通过 SSO 登录一次，确认使用新证书可以正常登录。
6. 从 SSO 卡片中移除旧证书，然后选择 **保存**。
7. 如果轮换前已启用 **强制单点登录**，请重新开启它，然后选择 **保存**。

SSO 卡片上的证书发生任何变化（无论添加还是移除）都会自动关闭 **强制单点登录**，因为新的设置还没有经过登录验证。只有在新证书验证可用后，才恢复之前的强制设置。

如果 Entra ID 使用 SSO 卡片中没有的证书签名（例如新证书在添加到控制面之前就被激活），所有登录都会以 `SSO_RESPONSE_INVALID` 失败。

## 故障排查[​](#troubleshooting "故障排查的直接链接")

Entra ID 的错误会在用户输入凭据之后显示在 Microsoft 页面上。控制面的错误会让浏览器回到控制台登录页面，并在页面上说明原因。SSO 错误码的完整列表参见[故障排查](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#troubleshooting)。

| 现象                                                                                                                                                            | 原因                                                                                                                     | 解决方法                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AADSTS50011: The reply URL ... does not match the reply URLs configured for the application`                                                                   | Entra ID 中的 **Reply URL** 与 SSO 卡片上的回复 URL 不一致，常见原因是登记应用后控制面的公开 URL 发生了变化。            | 将 SSO 卡片上的 **断言消费服务 URL（回复 URL）** 重新复制到 **Basic SAML Configuration** 中。                                                                                                                                            |
| `AADSTS50105: Your administrator has configured the application ... to block users unless they are specifically granted ('assigned') access to the application` | 该用户没有直接或通过组分配到该应用。                                                                                     | 在 **Users and groups** 中分配该用户或其所在的组。                                                                                                                                                                                       |
| My Apps 中显示 **App launch failed**                                                                                                                            | **Sign on URL** 是 `http://` URL。                                                                                       | 使用控制面的 HTTPS 登录 URL。                                                                                                                                                                                                            |
| 每次首次登录都进入关联页面，且没有邮箱地址                                                                                                                      | 应用没有声明配置，Entra ID 发送的是成对标识符形式的 NameID，且不发送 `emailaddress` 声明；或者用户没有 `mail` 值。       | 在 **Attributes & Claims** 中添加默认声明，参见[检查属性和声明](#check-the-attributes-and-claims)。也可以把 SSO 卡片上的 **邮箱属性** 设为 `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`，Entra ID 会在该声明中填入 UPN。 |
| `SSO_ACCOUNT_ALREADY_LINKED`                                                                                                                                    | 用户的 NameID 自首次登录以来发生了变化：NameID 为 UPN 时用户被改名，或 **Unique User Identifier (Name ID)** 声明被修改。 | 将该用户移出组织再重新加入。为避免这种情况，请使用 `user.objectid` 作为 NameID。                                                                                                                                                         |
| `SSO_UNSOLICITED_RESPONSE`                                                                                                                                      | 登录由 Entra ID 发起，例如在未填写 **Sign on URL** 时从 My Apps 打开。                                                   | 在 **Basic SAML Configuration** 中填写 **Sign on URL**，并从控制台发起登录。                                                                                                                                                             |
| `SSO_RESPONSE_INVALID`                                                                                                                                          | Entra ID 使用 SSO 卡片中没有的证书对响应签名。                                                                           | 将当前激活的证书添加到 SSO 卡片，或重新读取当前的联合元数据。                                                                                                                                                                            |
| `SSO_ENCRYPTED_ASSERTION_UNSUPPORTED`                                                                                                                           | 该应用开启了 Token 加密。                                                                                                | 在 Entra ID 中关闭 Token 加密。                                                                                                                                                                                                          |
| `SSO_NOT_A_MEMBER`                                                                                                                                              | 此人已在 Entra ID 中分配，但不是组织成员，且未开启 JIT 预配。                                                            | 邀请此人、通过 SCIM 预配，或开启 **登录时自动添加新成员（JIT）**。                                                                                                                                                                       |

## 下一步[​](#next-steps "下一步的直接链接")

使用 [SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md)在成员首次登录前从 Entra ID 预配和取消预配成员，使用[角色与权限](https://docs.apiseven.com/ai-gateway/cloud/custom-roles.md)定义可由角色映射规则分配的角色。
