跳到主要内容
版本：1.6.0

集成 Microsoft Entra ID

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

以下步骤按管理员实际操作的顺序排列，在 Microsoft Entra 管理中心与 AISIX Cloud 控制台之间来回切换。配置完成后 SSO 的行为（包括成员加入、角色映射、强制单点登录和会话）请参见单点登录（SAML）。

前提条件​

开始之前，请确认：

  • 你是 AISIX Cloud 组织的 Owner。只有 Owner 可以修改 SSO 连接。
  • 你在 Microsoft Entra ID 中拥有可创建和配置企业应用的角色，例如 Cloud Application Administrator 或 Application Administrator。
  • 浏览器能通过 HTTPS 访问 AISIX Cloud 控制面的公开 URL。在 On-Premises 控制面上，该地址即 AISIX_CLOUD_PUBLIC_BASE_URL，在 Helm Chart 中为 api.publicBaseURL。参见运行时 URL。

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

创建企业应用​

为 AISIX Cloud 创建一个非库应用：

  1. 登录 Microsoft Entra 管理中心，进入 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 页面，后续步骤都在这个页面上进行。

复制服务提供方信息​

在 AISIX Cloud 控制台中打开 设置，找到 单点登录（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 中完成应用登记。这些值的生成方式参见服务提供方信息。

填写基本 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。AISIX Cloud 只接受由它自己发起的登录。填写登录 URL 后，My Apps 中的应用磁贴会打开 AISIX Cloud 的登录页面，由该页面发起登录。如果不填写，点击磁贴会让 Entra ID 发送一个 AISIX Cloud 并未请求的响应，AISIX Cloud 会以 SSO_UNSOLICITED_RESPONSE 拒绝它。

检查属性和声明​

AISIX Cloud 从 SAML 断言中读取三项值：

  • 名称标识符（NameID），用于识别此人。首次登录之后，AISIX Cloud 只按它识别此人，因此它不能随此人的邮箱地址或用户名变化。参见身份关联。
  • 邮箱地址，取自 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 声明。该声明不存在时，如果 NameID 是邮箱格式，AISIX Cloud 会改用它。在 AISIX Cloud 信任身份提供方断言该地址的情况下，首次登录按这个地址匹配账号。参见首次登录。
  • 显示名称，取自 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name 声明；该声明不存在时，拼接 givenname 和 surname 声明。AISIX Cloud 在创建账号时，以及在 SaaS 服务上登录接管一个为该地址注册却从未验证邮箱的账号时，用显示名称设置账号名称。已验证过邮箱的账号保留原名称，之后的登录也不会修改它。

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

声明源属性
Unique User Identifier (Name ID)user.userprincipalname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressuser.mail
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameuser.userprincipalname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givennameuser.givenname
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surnameuser.surname

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

然后把 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。

使用对象 ID 作为 NameID 时，邮箱地址只来自 emailaddress 声明，即 user.mail；用户没有 mail 值时，Entra ID 不会发送该声明。这样的用户仍可登录，但 AISIX Cloud 收不到其邮箱地址，因此首次登录总会进入关联页面，且只能关联已有账号。如果想改用 UPN 作为邮箱地址，请把 SSO 卡片上的 邮箱属性 设为携带 UPN 的 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name。

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

不要为该应用开启令牌加密，AISIX Cloud 不接受加密的断言。Entra ID 使用 RSA-SHA256 对断言签名，不对响应签名，AISIX Cloud 接受这种方式。

如果同时通过 SCIM 从 Entra ID 预配用户，那么地址在组织已验证域名以外的用户，会在以等于 SCIM 所发送 externalId 的 NameID 关联 SSO 时加入。请把同一个 Entra ID 属性同时映射到两者，例如 NameID 为 user.objectid 时，在预配的属性映射中把 objectId 映射到 externalId。参见等待加入的成员。

定义应用角色​

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

  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 声明中发送的值，也是 AISIX Cloud 角色映射规则比较的值，区分大小写。

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

使用组代替应用角色​

推荐使用应用角色，但规则也可以读取 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 可以只发送分配给该应用的组，使声明保持精简。

分配用户和组​

应用的 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，且分配只覆盖组的直接成员。

应用角色的变更会在该人员下次登录 AISIX Cloud 时生效。

下载联合元数据​

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

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

在 AISIX Cloud 中配置连接​

在 AISIX Cloud 控制台中打开 设置 > 单点登录（SAML），完成连接配置：

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

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

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

  3. 开启 启用单点登录。

  4. 如果希望尚不是成员的人在首次登录时加入组织，开启 登录时自动添加新成员（JIT）；否则请先邀请他们，或通过 SCIM 预配。

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

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

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

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

  8. 选择 保存。

存在角色映射规则时，AISIX Cloud 会在每次登录时设置成员角色，因此在控制台中手动修改的角色会在成员下次登录时被替换。Owner 永远不会被修改。参见将身份提供方属性映射为角色。

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

测试登录​

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

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

浏览器会回到 AISIX Cloud。在 On-Premises 控制面上，或在 SaaS 服务上且用户的邮箱地址位于组织的某个已验证域名内时，会直接进入该组织。否则在 SaaS 服务上，首次登录会进入关联页面，用户在此关联账号并确认；之后的登录直接进入组织。在 成员 页面上，确认该成员的角色与其应用角色映射的角色一致。

成员也可以从常规登录页面 <public-base-url>/login 开始登录。在 On-Premises 控制面上，该页面会显示 使用 <组织> 的 SSO 登录 按钮，点击后直接跳转到 Entra ID。在 SaaS 服务上，成员选择 使用 SSO 登录，再输入组织标识，即登录 URL 中的 <org-slug>。参见通过 SSO 登录。

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

从 My Apps 登录​

已分配的用户还会在 My Apps 中看到该应用的磁贴。点击磁贴会打开 AISIX Cloud 的登录 URL，用户需要在该页面上再选择一次 使用 SSO 登录。由于 Entra ID 已有该用户的会话，之后的登录无需再次输入凭据即可完成。

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

强制单点登录​

测试登录成功后，可以让 SSO 成为 Owner 以外的成员访问组织的唯一方式。在 SSO 卡片上开启 强制单点登录，然后选择 保存。Owner 仍可用密码登录，从而在 Entra ID 不可用或配置错误时保留进入组织的途径。参见强制单点登录。

轮换签名证书​

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

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

SSO 卡片上的证书发生任何变化（无论添加还是移除）都会自动关闭 强制单点登录，因为新的设置还没有经过登录验证。这就是要在最后才重新开启它的原因。

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

故障排查​

Entra ID 的错误会在用户输入凭据之后显示在 Microsoft 页面上。AISIX Cloud 的错误会让浏览器回到 AISIX Cloud 登录页面，并在页面上说明原因。AISIX Cloud 错误码的完整列表参见故障排查。

现象原因解决方法
AADSTS50011: The reply URL ... does not match the reply URLs configured for the applicationEntra 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 failedSign on URL 是 http:// URL。使用控制面的 HTTPS 登录 URL。
每次首次登录都进入关联页面，且没有邮箱地址应用没有声明配置，Entra ID 发送的是成对标识符形式的 NameID，且不发送 emailaddress 声明；或者用户没有 mail 值。在 Attributes & 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) 声明被修改。将该用户移出 AISIX Cloud 组织再重新加入。为避免这种情况，请使用 user.objectid 作为 NameID。
SSO_UNSOLICITED_RESPONSE登录由 Entra ID 发起，例如在未填写 Sign on URL 时从 My Apps 打开。在 Basic SAML Configuration 中填写 Sign on URL，并从 AISIX Cloud 发起登录。
SSO_RESPONSE_INVALIDEntra ID 使用 SSO 卡片中没有的证书对响应签名。将当前激活的证书添加到 SSO 卡片，或重新读取当前的联合元数据。
SSO_ENCRYPTED_ASSERTION_UNSUPPORTED该应用开启了令牌加密。在 Entra ID 中关闭令牌加密。
SSO_NOT_A_MEMBER此人已在 Entra ID 中分配，但不是 AISIX Cloud 组织的成员，且未开启 JIT 预配。邀请此人、通过 SCIM 预配，或开启 登录时自动添加新成员（JIT）。

下一步​

使用 SCIM 目录同步在成员首次登录前从 Entra ID 预配和取消预配成员，使用角色与自定义角色定义 member 和 admin 以外、可由角色映射规则分配的角色。