重要
自 2025 年 5 月 1 日起,Azure AD B2C 将不再可供新客户购买。 在我们的常见问题解答中了解详细信息。
Azure Active Directory B2C(Azure AD B2C)会在处理每个 身份验证流时发出不同类型的安全令牌。 本文介绍每种类型的令牌的格式、安全特征和内容。
Azure AD B2C 支持 OAuth 2.0 和 OpenID Connect 协议,该协议利用令牌进行身份验证和安全访问资源。 Azure AD B2C 中使用的所有令牌都是 JSON Web 令牌(JWT), 其中包含有关持有者和令牌主体信息的断言。
以下令牌用于与 Azure AD B2C 通信:
ID 令牌 - 包含可用于标识应用程序中用户的声明的 JWT。 此令牌在 HTTP 请求中安全地发送,以便在同一应用程序或服务的两个组件之间进行通信。 可以按照你的意愿在 ID 令牌中使用声明。 它们通常用于显示帐户信息或在应用程序中做出访问控制决策。 Azure AD B2C 颁发的 ID 令牌已签名,但未加密。 当应用程序或 API 收到 ID 令牌时,它必须验证签名,以证明令牌是真实的。 应用程序或 API 还必须验证令牌中的一些声明,以证明它有效。 根据方案要求,应用程序验证的声明可能会有所不同,但应用程序必须在每个方案中执行一些常见的声明验证。
访问令牌 - 一个 JWT,其中包含可以用来识别授予你 API 权限的声明。 访问令牌已签名,但未加密。 访问令牌用于提供对 API 和资源服务器的访问。 当 API 收到访问令牌时,它必须验证签名以证明令牌是真实的。 API 还必须验证令牌中的一些声明,以证明其有效。 根据方案要求,应用程序验证的声明可能会有所不同,但应用程序必须在每个方案中执行一些常见的声明验证。
刷新令牌 - 刷新令牌 用于获取 OAuth 2.0 流中的新 ID 令牌和访问令牌。 它们为应用程序提供代表用户长期访问资源的权限,而无需与这些用户交互。 刷新令牌对应用程序而言是不可见的。 它们由 Azure AD B2C 颁发,只能由 Azure AD B2C 进行检查和解释。 它们寿命较长,但应用程序不应假设刷新令牌在特定时间段内持续有效而进行编写。 由于各种原因,刷新令牌随时可能失效。 应用程序了解刷新令牌是否有效的唯一方法是尝试通过向 Azure AD B2C 发出令牌请求来兑换它。 在用刷新令牌换取新令牌时,会在令牌响应中收到新的刷新令牌。 保存新的刷新令牌。 它会替换您之前在请求中使用过的刷新令牌。 此操作有助于保证您的刷新令牌保持尽可能长时间有效。 将授权代码流与 PKCE 配合使用的单页应用程序始终刷新令牌生存期为 24 小时。 详细了解浏览器中刷新令牌的安全影响。
注册的应用程序通过向以下终结点发送请求来接收令牌并与 Azure AD B2C 通信:
https://<tenant-name>.b2clogin.cn/<tenant-name>.partner.onmschina.cn/<policy-name>/oauth2/v2.0/authorize
https://<tenant-name>.b2clogin.cn/<tenant-name>.partner.onmschina.cn/<policy-name>/oauth2/v2.0/token
应用程序从 Azure AD B2C 接收的安全令牌可以来自于 /authorize
和 /token
两个终结点。 从以下来源/资源获取 ID 令牌时:
-
/authorize
终结点是使用 隐式流完成的,该流通常用于登录到基于 JavaScript 的 Web 应用程序的用户。 但是,如果你的应用使用 MSAL.js 2.0 或更高版本,请不要在应用注册中启用隐式流授予,因为 MSAL.js 2.0+ 支持使用 PKCE 的授权代码流。 -
/token
终结点是使用 授权代码流完成的,该流将令牌隐藏在浏览器中。
使用 Azure AD B2C 时,可以精细控制令牌的内容。 可以将 用户流 和 自定义策略 配置为在应用程序所需的声明中发送某些用户数据集。 这些声明可以包括标准属性,例如 displayName 和 emailAddress。 应用程序可以使用这些声明安全地对用户和请求进行身份验证。
ID 令牌中的声明不会按任何特定顺序返回。 可以随时在 ID 令牌中引入新声明。 应用程序在引入新声明时不应出现故障。 还可以在声明中包括 自定义用户属性 。
下表列出了您可以在 Azure AD B2C 颁发的 ID 令牌和访问令牌中预期的声明。
名称 | 索赔 | 示例值 | DESCRIPTION |
---|---|---|---|
观众 | aud |
00001111-aaaa-2222-bbbb-3333cccc4444 |
标识令牌的目标接收方。 对于 Azure AD B2C,受众是应用程序 ID。 应用程序应验证此值,并在不匹配时拒绝令牌。 受众被视为资源的同义词。 |
发行人 | iss |
https://<tenant-name>.b2clogin.cn/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/ |
标识构造并返回令牌的安全令牌服务(STS)。 它还标识用户进行身份验证的目录。 应用程序应验证颁发者声明,以确保令牌来自相应的终结点。 |
颁发时间 | iat |
1438535543 |
颁发令牌的时间,以纪元时间表示。 |
过期时间 | exp |
1438539443 |
令牌失效的时间,以纪元时间表示。 应用程序应使用此声明来验证令牌生存期的有效性。 |
生效时间 | nbf |
1438535543 |
令牌生效的时间,以纪元时间表示。 这一次通常与颁发令牌的时间相同。 应用程序应使用此声明来验证令牌生存期的有效性。 |
版本 | ver |
1.0 |
由 Azure AD B2C 定义的 ID 令牌版本。 |
代码哈希 | c_hash |
SGCPtt01wxwfgnYZy2VJtQ |
当且仅当 ID 令牌与 OAuth 2.0 授权代码一起颁发时,代码哈希才会包含在 ID 令牌中。 代码哈希可用于验证授权代码的真实性。 有关如何执行此验证的详细信息,请参阅 OpenID Connect 规范。 |
访问令牌哈希 | at_hash |
SGCPtt01wxwfgnYZy2VJtQ |
仅当 OAuth 2.0 访问令牌与 ID 令牌一起颁发时,ID 令牌中才包含访问令牌哈希。 访问令牌哈希可用于验证访问令牌的真实性。 有关如何执行此验证的详细信息,请参阅 OpenID Connect 规范 |
随机数 | nonce |
12345 |
nonce 是用于防止令牌重播攻击的一种策略。 您的应用程序可以使用 nonce 查询参数在授权请求中指定 nonce。 请求中提供的值仅在 ID 令牌的nonce 声明中被原样发出。 此声明允许应用程序根据请求中指定的值验证值。 应用程序应在 ID 令牌验证过程中执行此验证。 |
使用者 | sub |
aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb |
令牌针对其断言信息的主体,例如应用程序的用户。 此值是不可变的,无法重新分配或重复使用。 它可用于安全地执行授权检查,例如,使用令牌访问资源时。 默认情况下,使用者声明会以目录中用户的对象 ID 进行填充。 |
身份验证上下文类参考 | acr |
不適用 | 仅用于较旧的策略。 |
信任框架策略 | tfp |
b2c_1_signupsignin1 |
用于获取 ID 令牌的策略的名称。 |
身份验证时间 | auth_time |
1438535543 |
用户上次输入凭据的时间,以纪元时间表示。 身份验证是全新登录、单一登录(SSO)会话或其他登录类型之间没有区别。
auth_time 这是应用程序(或用户)上次针对 Azure AD B2C 发起身份验证尝试的时间。 用于进行身份验证的方法没有区别。 |
范围 | scp |
Read |
向资源授予访问令牌的权限。 多个授予的权限由一个空格分隔。 |
授权方 | azp |
975251ed-e4f5-4efd-abcb-5f1a8f566ab7 |
发起请求的客户端应用程序的应用程序 ID。 |
以下属性用于管理 Azure AD B2C 发出的 安全令牌的生存期 :
访问和 ID 令牌生存期(分钟) - 用于获取对受保护资源的访问的 OAuth 2.0 持有者令牌的生存期。 默认值为 60 分钟。 最小值(含)为 5 分钟。 最大值(含)为 1,440 分钟。
刷新令牌生存期 (天) - 在此期间,刷新令牌可以被使用以获取新的访问或 ID 令牌的最长时间。 如果你的应用程序被授予了
offline_access
范围,这段时间内还包括获取新的刷新令牌。 默认值为 14 天。 最小值为 1 天(含)。 最大值(含)为 90 天。刷新令牌滑动窗口生存期 (天) - 在此时间段过后,用户被迫重新进行身份验证,而不考虑应用程序获取的最新刷新令牌的有效期。 仅当开关设置为 Bounded 时,才能提供它。 它需要大于或等于 刷新令牌生存期(天) 值。 如果开关设置为 “无过期”,则无法提供特定值。 默认为 90 天。 最小值为 1 天(含)。 最大值(含)为 365 天。
通过这些属性启用以下用例:
- 允许用户无限期地登录到移动应用程序,只要用户在应用程序中持续处于活动状态。 可以将 刷新令牌滑动窗口生存期(天) 设置为登录用户流中 未过期 。
- 通过设置适当的访问令牌生存期来满足行业的安全性和合规性要求。
这些设置不适用于密码重置用户流。
以下属性用于 管理令牌兼容性:
发行者(iss)声明 - 此属性标识发行令牌的 Azure AD B2C 租户。 默认值是
https://<domain>/{B2C tenant GUID}/v2.0/
。https://<domain>/tfp/{B2C tenant GUID}/{Policy ID}/v2.0/
的值包括 Azure AD B2C 租户的 ID 以及用于令牌请求的用户流的 ID。 如果应用程序或库需要 Azure AD B2C 符合 OpenID Connect Discovery 1.0 规范,请使用此值。Subject (sub) 声明 - 此属性用于标识令牌所声明信息的实体。 默认值为 ObjectID,它使用用户的对象 ID 填充
sub
令牌中的声明。 不支持的值仅用于向后兼容性。 建议您在能够时尽快切换到ObjectID。表示策略 ID 的声明 - 此属性标识在令牌请求中使用的策略名称填充到的声明类型。 默认值是
tfp
。 该值acr
仅提供用于向后兼容。
用户旅程开始时,Azure AD B2C 会从标识提供者接收访问令牌。 Azure AD B2C 使用该令牌检索有关用户的信息。 在您的用户流中启用声明,以便将令牌顺利传递到您在 Azure AD B2C 中注册的应用程序中。 您的应用程序必须使用建议的用户流,以利用将令牌作为声明传递的优势。
Azure AD B2C 目前仅支持传递 OAuth 2.0 标识提供者的访问令牌。 对于所有其他标识提供者,声明将返回空白。
若要验证令牌,应用程序应同时检查令牌的签名和声明。 许多开源库可用于验证 JWT,具体取决于首选语言。 建议浏览这些选项,而不是实现自己的验证逻辑。
JWT 包含三个段、 标头、 正文和 签名。 签名段可用于验证令牌的真实性,以便应用程序可以信任该令牌。 Azure AD B2C 令牌使用行业标准非对称加密算法(如 RSA 256)进行签名。
令牌的标头包含有关用于对令牌进行签名的密钥和加密方法的信息:
{
"typ": "JWT",
"alg": "RS256",
"kid": "GvnPApfWMdLRi8PDmisFn7bprKg"
}
alg 声明的值是用于对令牌进行签名的算法。 kid声明的值是用于对令牌进行签名的公钥。 在任何给定时间,Azure AD B2C 都可以使用一组公钥-私钥对中的任何一个对令牌进行签名。 Azure AD B2C 会定期轮换可能的密钥集。 应编写应用程序以自动处理这些密钥更改。 检查 Azure AD B2C 使用的公钥更新的合理频率为每 24 小时一次。 若要处理意外的密钥更改,应用程序应在收到意外的 kid 值时重新检索公钥。
Azure AD B2C 具有 OpenID Connect 元数据终结点。 使用此终结点,应用程序可以在运行时请求有关 Azure AD B2C 的信息。 此信息包括终结点、令牌内容和令牌签名密钥。 Azure AD B2C 租户为每个策略提供一个 JSON 元数据文档。 元数据文档是一个 JSON 对象,其中包含多个有用的信息片段。 元数据包含 jwks_uri,它提供用于对令牌进行签名的公钥集的位置。 此处提供了该位置,但最好使用元数据文档动态提取位置并分析 jwks_uri:
https://contoso.b2clogin.cn/contoso.partner.onmschina.cn/b2c_1_signupsignin1/discovery/v2.0/keys
位于此 URL 的 JSON 文档包含特定时刻使用的所有公钥信息。 应用可以使用 kid
JWT 标头中的声明来选择用于对特定令牌进行签名的 JSON 文档中的公钥。 然后,它可以使用正确的公钥和指示的算法来执行签名验证。
租户中contoso.partner.onmschina.cn
策略的B2C_1_signupsignin1
元数据文档位于:
https://contoso.b2clogin.cn/contoso.partner.onmschina.cn/b2c_1_signupsignin1/v2.0/.well-known/openid-configuration
若要确定用于对令牌进行签名的策略(以及用于请求元数据的位置),有两个选项。 首先,策略名称包含在令牌中的 tfp
(默认)或 acr
声明(已配置)。 可以通过对正文进行 base-64 解码并反序列化结果的 JSON 字符串来分析 JWT 正文中的声明。
tfp
或acr
声明是用于颁发令牌的策略的名称。 另一个选项是在发出请求时在参数的值 state
中对策略进行编码,然后对其进行解码以确定使用了哪个策略。 任意一种方法均有效。
Azure AD B2C 使用 RS256 算法,该算法基于 RFC 3447 规范。 公钥由两个组件组成:RSA 模数(n
)和 RSA 公共指数(e
)。 你可以以编程方式将值转换为n
e
用于令牌验证的证书格式。
有关如何执行签名验证的说明超出了本文档的范围。 许多开源库都可用于帮助你验证令牌。
当应用程序或 API 收到 ID 令牌时,它还应该对 ID 令牌中的声明执行多次检查。 应检查以下声明:
- 受众 - 验证 ID 令牌是否旨在提供给你的应用程序。
- 不得早于 和 过期时间 - 验证 ID 令牌尚未过期。
- 颁发者 - 验证令牌是否已由 Azure AD B2C 颁发给应用程序。
- nonce - 一种用于防范令牌重播攻击的策略。
有关应用程序应执行的验证的完整列表,请参阅 OpenID Connect 规范。
详细了解如何使用 访问令牌。