集成 Microsoft Entra ID
本指南通过 SAML 单点登录(SSO)把 AISIX Enterprise 或 AISIX Cloud 组织与 Microsoft Entra ID 连接起来。完成后,分配到 Entra ID 企业应用的人员可以用其 Entra ID 账号登录控制台,并由你为其分配的 Entra ID 应用角色决定其在组织中的角色。
以下步骤按管理员实际操作的顺序排列,在 Microsoft Entra 管理中心与控制台之间来回切换。配置完成后 SSO 的行为(包括成员加入、角色映射、强制单点登录和会话)请参见单点登录(SAML)。
前提条件
开始之前,请确认:
- 你拥有组织的 所有者 角色。只有所有者可以修改 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。
Entra ID 只对 localhost 接受 http:// 回复 URL,而 My Apps 磁贴完全无法打开 http:// 登录 URL,因此纯 HTTP 的控制面只适合本地测试。
创建企业应用
为控制面创建一个非库应用:
- 登录 Microsoft Entra 管理中心,进入 Entra ID > Enterprise apps > All applications。
- 选择 New application,然后选择 Create your own application。
- 输入名称(例如
AISIX),选择 Integrate any other application you don't find in the gallery (Non-gallery),然后选择 Create。 - 在新应用的 Manage 下选择 Single sign-on,再选择 SAML。
随后会打开 Set up Single Sign-On with SAML 页面,后续步骤都在这个页面上进行。
复制服务提供方信息
在控制台中打开 设置,选择 身份认证 标签页,找到 单点登录(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。控制面只接受由它自己发起的登录。填写登录 URL 后,My Apps 中的应用磁贴会打开控制台登录页面,由该页面发起登录。如果不填写,点击磁贴会让 Entra ID 发送一个控制面并未请求的响应,控制面会以 SSO_UNSOLICITED_RESPONSE 拒绝它。
检查属性和声明
控制面从 SAML 断言中读取三项值:
- 名称标识符(NameID),用于识别此人。首次登录之后,控制面只按它识别此人,因此它不能随此人的邮箱地址或用户名变化。参见身份关联。
- 邮箱地址,取自
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress声明。该声明不存在时,如果 NameID 是邮箱格式,控制面会改用它。在控制面信任身份提供方断言该地址的情况下,首次登录按这个地址匹配账号。参见首次登录。 - 显示名称,取自
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name声明;该声明不存在时, 拼接givenname和surname声明。控制面在创建账号时,以及在 AISIX Cloud 中登录接管一个为该地址注册却从未验证邮箱的账号时,用显示名称设置账号名称。已验证过邮箱的账号保留原名称,之后的登录也不会修改它。
在 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:
- 选择 Unique User Identifier (Name ID) 声明。
- 将 Name identifier format 设为 Persistent,Source attribute 设为
user.objectid。 - 选择 Save。
默认的 NameID,即用户主体名称(UPN),也可以使用 ,但用户改名时 UPN 会变化。改名后的用户会被拒绝并返回 SSO_ACCOUNT_ALREADY_LINKED,直到被移出组织再重新加入。请在成员开始登录之前完成这项修改:之后再改 NameID,对所有已经登录过的人都会产生同样的影响。参见之后更改 NameID。
使用对象 ID 作为 NameID 时,邮箱地址只来自 emailaddress 声明,即 user.mail;用户没有 mail 值时,Entra ID 不会发送该声明。这样的用户仍可登录,但控制面收不到其邮箱地址,因此首次登录总会进入关联页面,且只能关联已有账号。如果想改用 UPN 作为邮箱地址,请把 SSO 卡片上的 邮箱属性 设为携带 UPN 的 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name。
如果希望控制台显示人员姓名而不是 UPN,请把 name 声明的源属性改为 user.displayname。
不要为该应用开启 Token 加密,控制面不接受加密的断言。Entra ID 使用 RSA-SHA256 对断言签名,不对响应签名,控制面接受这种方式。
如果同时通过 SCIM 从 Entra ID 预配用户,那么地址在组织已验证域名以外的用户,会在以等于 SCIM 所发送 externalId 的 NameID 关联 SSO 时加入。请把同一个 Entra ID 属性同时映射到两者,例如 NameID 为 user.objectid 时,在预配的属性映射中把 objectId 映射到 externalId。参见等待加入的成员。
定义应用角色
应用角色用来让 Entra ID 告诉控制面每个人应具有的角色。请为每个不同于连接默认角色的组织角色定义一个应用角色。以管理员的应用角色为例:
- 在 Microsoft Entra 管理中心进入 Entra ID > App registrations,选择 All applications,然后选择你创建的应用。它与企业应用同名。
- 在 Manage 下选择 App roles,然后选择 Create app role。
- 输入 Display name(例如
AISIX Admin),将 Allowed member types 设为 Users/Groups,输入 Value(例如AISIX.Admin),并填写 Description。 - 保持勾选 Do you want to enable this app role?,然后选择 Apply。
Value 就是 Entra ID 在 http://schemas.microsoft.com/ws/2008/06/identity/claims/role 声明中发送的值,也是角色映射规则比较的值,区分大小写。
没有应用角色、或其应用角色没有被任何规则命中的人,会获得连接的默认角色,无需为他们定义应用角色。
使用组代替应用角色
推荐使用应用角色,但规则也可以读取 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 中查看该属性。分配人员的步骤如下:
- 在企业应用的 Manage 下选择 Users and groups,然后选择 Add user/group。
- 在 Users and groups 中选择应能登录的用户或组,然后选择 Select。
- 在 Select a role 中为其选择应用角色(例如
AISIX Admin),然后选择 Select。应获得默认角色的人员可跳过此步。 - 选择 Assign。
分配组需要 Microsoft Entra ID P1 或 P2,且分配只覆盖组的直接成员。
应用角色的变更会在该人员下次通过控制台登录时生效。
下载联合元数据
在 Set up Single Sign-On with SAML 页面的 SAML Certificates 部分,选择 Federation Metadata XML 旁的 Download。
该文件描述了作为身份提供方的 Entra ID:它的实体 ID、登录 URL 和签名证书。
在控制台中配置连接
在控制台中打开 设置 > 身份认证 > 单点登录(SAML),完成连接配置:
-
将元数据粘贴到 身份提供商元数据 XML 中并选择 读取元数据,或选择 上传元数据文件 并选择下载的文件。
-
检查元数据填写的字段:
- 身份提供商实体 ID:
https://sts.windows.net/<tenant-id>/ - 单点登录 URL:
https://login.microsoftonline.com/<tenant-id>/saml2 - 签名证书:一个证书。元数据会在多处重复同一证书,控制面只保留一份。
- 身份提供商实体 ID:
-
开启 启用单点登录。
-
如果希望尚不是成员的人在首次登录时加入组织,开启 登录时自动添加新成员(JIT);否则请先邀请他们,或通过 SCIM 预配。
-
默认角色 保持为 受限成员,或选择没有命中应用角色的人员应获得的角色。
-
在 角色映射 下选择 添加规则,为管理员应用角色填写规则:
属性 运算符 值 角色 http://schemas.microsoft.com/ws/2008/06/identity/claims/role任一值等于 AISIX.Admin管理员 -
邮箱属性 和 显示名称属性 留空,使用默认值。
-
选择 保存。
存在角色映射规则时,控制面会在每次登录时重新设置 SSO 分配的角色,因此失去 AISIX.Admin 应用角色的成员会在下次登录时失去 管理员。手动分配的角色和通过团队持有的角色不受影响,所有者也不会被修改。参见将身份提供方属性映射为角色。
也可以不用元数据,手动填写这三个字段。在 Entra ID 的 Set up Single Sign-On with SAML 页面上,它们分别是设置应用部分中的 Microsoft Entra Identifier 和 Login URL,以及 SAML Certificates 中的 Certificate (Base64) 下载项。
测试登录
在浏览器隐私窗口中,用一个已分配到该应用的用户测试:
- 打开登录 URL
<public-base-url>/login?sso=<org-slug>。 - 选择 使用 SSO 登录。
- 用该用户的账号登录 Microsoft。
浏览器会回到控制台。在 AISIX Enterprise 中,或在 AISIX Cloud 中且用户的邮箱地址位于组织的某个已验证域名内时,会直接进入该组织。否则 在 AISIX Cloud 中,首次登录会进入关联页面,用户在此关联账号并确认;之后的登录直接进入组织。在 成员 页面上,确认该成员的角色与其应用角色映射的角色一致。
成员也可以从常规登录页面 <public-base-url>/login 开始登录。在 AISIX Enterprise 中,该页面会显示 使用 <组织> 的 SSO 登录 按钮,点击后直接跳转到 Entra ID。在 AISIX Cloud 中,成员选择 使用 SSO 登录,再输入组织标识,即登录 URL 中的 <org-slug>。参见通过 SSO 登录。
多重身份验证(包括 Microsoft 安全默认值和条件访问)在控制面收到响应之前就已在 Entra ID 中完成,控制面中无需为此做任何配置。尚未注册验证方式的测试用户可能会先被 Microsoft 要求注册一种验证方式。
从 My Apps 登录
已分配的用户还会在 My Apps 中看到该应用的磁贴。点击磁贴会打开控制台的登录 URL,用户需要在该页面上再选择一次 使用 SSO 登录。由于 Entra ID 已有该用户的会话,之后的登录无需再次输入凭据即可完成。
磁贴只适用于 HTTPS 的 Sign on URL。如果登录 URL 是 http://(即使是 localhost),My Apps 会报告 App launch failed。如果没有填写登录 URL,控制面会以 SSO_UNSOLICITED_RESPONSE 拒绝登录 。
强制单点登录
测试登录成功后,可以让 SSO 成为所有者以外的成员访问组织的唯一方式。在 SSO 卡片上开启 强制单点登录,然后选择 保存。所有者仍可用密码登录,从而在 Entra ID 不可用或配置错误时保留进入组织的途径。参见强制单点登录。
轮换签名证书
Entra ID 为应用创建的签名证书有效期为三年,并会在证书到期前向 SAML Signing Certificate 页面上的通知邮箱发送提醒。一个 SSO 连接最多保存 10 个证书,由其中任一证书签名的响应都会被接受,因此可以在不中断登录的情况下轮换。
轮换证书前,请记录是否已启用 强制单点登录。修改证书列表会将其关闭。
按以下顺序操作:
- 在 Entra ID 的 SAML Certificates 部分选择 Edit。在 SAML Signing Certificate 页面上选择 New Certificate,然后选择 Save。新证书的状态为 Inactive。
- 选择新证书旁的省略号(...),以 Base64 格式下载该证书。
- 在控制台的 SSO 卡片上选择 添加证书,粘贴证书后选择 保存。也可以重新下载 Federation Metadata XML(其中已同时包含新旧两个证书),再用 读取元数据 导入。
- 在 Entra ID 中选择新证书旁的省略号(...),选择 Make certificate active。
- 通过 SSO 登录一次,确认使用新证书可以正常登录。
- 从 SSO 卡片中移除旧证书,然后选择 保存。
- 如果轮换前已启用 强制单点登录,请重新开启它,然后选择 保存。
SSO 卡片上的证书发生任何变化(无论添加还是移除)都会自动关闭 强制单点登录,因为新的设置还没有经过登录验证。只有在新证书验证可用后,才恢复之前的强制设置。
如果 Entra ID 使用 SSO 卡片中没有的证书签名(例如新证书在添加到控制面之前就被激活),所有登录都会以 SSO_RESPONSE_INVALID 失败。
故障排查
Entra ID 的错误会在用户输入凭据之后显示在 Microsoft 页面上。控制面的错误会让浏览器回到控制台登录页面,并在页面上说明原因。SSO 错误码的完整列表参见故障排查。
| 现象 | 原因 | 解决方法 |
|---|---|---|
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 中添加默认声明,参见检查属性和声明。也可以把 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)。 |
下一步
使用 SCIM 目录同步在成员首次登录前从 Entra ID 预配和取消预配成员,使用角色与权限定义可由角色映射规则分配的角色。