访问令牌声明参考

  • 项目

访问令牌是 JSON Web 令牌 (JWT)。 JWT 包含以下部分：

  • 标头 - 提供有关如何验证令牌的信息，包括有关令牌的类型及其签名方法的信息。
  • 有效负载 - 包含有关正在尝试调用服务的用户或应用程序的所有重要数据。
  • 签名 - 用于验证令牌的原始材料。

每个部分由句点 (.) 分隔，并分别采用 Base 64 编码。

仅当存在可以填充声明的值时，才提供声明。 应用程序不应该依赖于所要提供的声明。 示例包括 pwd_exp（并非每个租户都要求密码过期）和 family_name（客户端凭据流代表无名称的应用程序）。 访问令牌将始终包含足够的声明才能进行访问评估。

Microsoft 标识平台使用一些声明来帮助保护令牌以供重复使用。 Opaque 的说明将这些声明标记为不适合公共使用。 这些声明可能会或可能不会出现在令牌中，并且可能在不发出通告的情况下添加新的声明。

标头声明

声明 格式 说明
typ 字符串 - 始终为 JWT 指示令牌是 JWT。
alg 字符串 指示用于对令牌进行签名的算法，例如 RS256。
kid 字符串 指定用于验证此令牌的签名的公钥的指纹。 在 v1.0 和 v2.0 访问令牌中已发出。
x5t 字符串 功能与 kid 相同（在用法和值方面）。 x5t，是在 v1.0 访问令牌中仅出于兼容目的而发出的旧式声明。

有效负载声明

声明 格式 说明 授权注意事项
acrs 字符串的 JSON 数组 表示持有者有资格执行的操作的身份验证上下文 ID。 可以使用上下文 AD 从应用程序和服务中触发对逐步身份验证的需求。 通常与 xms_cc 声明一起使用。
aud 字符串，一个应用程序 ID URI 或 GUID 标识令牌的目标受众。 在 v2.0 令牌中，此值始终是 API 的客户端 ID。 而在 v1.0 令牌中，它可以是客户端 ID 或请求中使用的资源 URI。 该值可取决于客户端请求令牌的方式。 必须验证此值，如果值与预期受众不匹配，则拒绝令牌。
iss 字符串，一个安全令牌服务 (STS) URI 标识构造并返回令牌的 STS，以及经过身份验证的用户的 Microsoft Entra 租户。 如果颁发的令牌是 v2.0 令牌（请参阅 ver 声明），则 URI 以 /v2.0 结尾。 表示用户是来自 Microsoft 帐户的使用者用户的 GUID 为 9188040d-6c67-4c5b-b112-36a304b66dad。 应用程序可以使用声明的 GUID 部分限制可登录应用程序的租户集（如果适用）。
idp 字符串，通常是 STS URI 记录对令牌使用者进行身份验证的标识提供者。 除非用户帐户与颁发者不在同一租户中（如来宾），否则此值与颁发者声明的值相同。 如果声明不存在，请使用 iss 的值。 对于在组织上下文中使用的个人帐户（例如，受邀加入 Microsoft Entra 租户的个人帐户），idp 声明可能是“live.com”或包含 Microsoft 帐户租户 9188040d-6c67-4c5b-b112-36a304b66dad 的 STS URI。
iat int，Unix 时间戳 指定针对此令牌进行身份验证的时间。
nbf int，Unix 时间戳 指定可以开始处理 JWT 的时间。
exp int，Unix 时间戳 指定过期时间，在此时间之前可接受 JWT 进行处理。 资源在此时间之前也可以拒绝令牌。 身份验证中需要更改，或在吊销令牌时，可能会发生拒绝。
aio 不透明字符串 一个内部声明，由 Microsoft Entra ID 用来记录数据，以便重用令牌。 资源不应使用此声明。
acr 字符串，一个 0 或 1，仅在 v1.0 令牌中提供 “身份验证上下文类”声明的 0 值指示最终用户身份验证不符合 ISO/IEC 29115 要求。
amr 字符串的 JSON 数组，仅在 v1.0 令牌中提供 标识令牌使用者的身份验证方法。
appid 字符串，一个 GUID，仅在 v1.0 令牌中提供 使用令牌的客户端的应用程序 ID。 该应用程序可以自身名义或者代表用户进行操作。 应用程序 ID 通常表示应用程序对象，但它还可以表示 Microsoft Entra ID 中的服务主体对象。 appid 可用于授权决策。
azp 字符串，一个 GUID，仅在 v2.0 令牌中提供 appid 的替换选项。 使用令牌的客户端的应用程序 ID。 该应用程序可以自身名义或者代表用户进行操作。 应用程序 ID 通常表示应用程序对象，但它还可以表示 Microsoft Entra ID 中的服务主体对象。 azp 可用于授权决策。
appidacr 字符串， 0、1 或 2，仅在 v1.0 令牌中提供 指示客户端的身份验证方法。 对于公共客户端，值为 0。 使用客户端 ID 和客户端密码时，该值为 1。 使用客户端证书进行身份验证时，值为 2。
azpacr 字符串， 0、1 或 2，仅在 v2.0 令牌中提供 appidacr 的替换选项。 指示客户端的身份验证方法。 对于公共客户端，值为 0。 使用客户端 ID 和客户端密码时，该值为 1。 使用客户端证书进行身份验证时，值为 2。
preferred_username 字符串，仅在 v2.0 令牌中提供。 表示用户的主用户名。 该值可以是电子邮件地址、电话号码或未指定格式的通用用户名。 将此值用于用户名提示，在人工可读的 UI 中用作用户名。 若要接收此声明，请使用 profile 范围。 由于此值可变，因此不要将其用于做出授权决策。
name 字符串 提供一个用户可读值，用于标识令牌使用者。 该值可以变化，它是可变的，仅用于显示目的。 若要接收此声明，请使用 profile 范围。 请勿使用此值做出授权决策。
scp 字符串，范围的空格分隔列表 应用程序公开的、客户端应用程序已请求（和接收）其许可的范围集。 仅为用户令牌包含此值。 应用程序应该验证这些范围是否为应用程序公开的有效范围，并根据这些范围的值做出授权决策。
roles 字符串数组、权限列表 应用程序公开的、请求方应用程序或用户有权调用的权限集。 对于应用程序令牌，客户端凭据流使用此权限集来取代用户范围。 对于用户令牌，此值集包含目标应用程序上分配的用户角色。 这些值可用于管理访问，例如强制要求授权才能访问资源。
wids RoleTemplateID GUID 的数组 表示分配给此用户的租户级角色，该角色来自Microsoft Entra 内置角色中显示的角色部分。 应用程序清单的 groupMembershipClaims 属性针对每个应用程序配置此声明。 将声明设置为 All 或 DirectoryRole。 由于令牌长度方面的原因，它在通过隐式流获取的令牌中可能不存在。 这些值可用于管理访问，例如强制要求授权才能访问资源。
groups GUID 的 JSON 数组 指定表示使用者的组成员身份的对象 ID。 应用程序清单的 groupMembershipClaims 属性针对每个应用程序配置组声明。 值为 null 会排除所有组；值为 SecurityGroup 会只包括“Active Directory 安全组”成员身份；值为 All 会包括安全组和 Microsoft 365 通讯组列表。

有关将 groups 声明与隐式授权一起使用的详细信息，请参阅 hasgroups 声明。 对于其他流，如果用户所在的组数对于 SAML 超过 150 个，对于 JWT 超过 200 个，则 Microsoft Entra ID 会向声明源添加一个超额声明。 声明源指向包含用户的组列表的 Microsoft Graph 终结点。		 这些值可用于管理访问，例如强制要求授权才能访问资源。
hasgroups 布尔 如果存在，则始终为 true，指示用户是否至少在一个组中。 如果完整组声明将导致 URI 片段超出 URL 长度限制（当前为 6 个或更多组），则在隐式授权流中用来替代 JWT 的 groups 声明。 指示客户端应当使用 Microsoft Graph API 来确定用户的组 (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects)。
groups:src1 JSON 对象 在令牌请求对于令牌来说太大时，包括指向用户的完整组列表的链接。 对于 JWT，作为分布式声明；对于 SAML，作为新声明替代 groups 声明。

JWT 值示例：
"groups":"src1"
"_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }
sub 字符串 与令牌关联的主体。 例如，应用程序的用户。 此值不可变，请勿重新分配或重复使用。 使用者是成对标识符，它对特定应用程序 ID 是唯一的。 如果单个用户使用两个不同的客户端 ID 登录两个不同的应用程序，这些应用程序将收到两个不同的使用者声明值。 对这两个不同的值的使用取决于体系结构和隐私要求。 另请参阅 oid 声明，它在租户内的各个应用程序中保持不变。 此值可用于执行授权检查（例如，使用令牌访问资源时），并可将它用作数据库表中的键。
oid 字符串，GUID 请求者的不可变标识符，即用户或服务主体的已验证标识。 此 ID 在应用程序间唯一标识请求者。 同一个用户登录两个不同的应用程序会在 oid 声明中收到相同值。 对 Microsoft 联机服务（例如 Microsoft Graph）发出查询时可以使用 oid。 Microsoft Graph 会返回此 ID 作为给定用户帐户的 id 属性。 因为 oid 允许多个应用程序关联主体，要接收用户的声明，请使用 profile 范围。 如果单个用户存在于多个租户中，该用户会包含每个租户中的不同对象 ID。 即使用户使用相同的凭据登录到每个帐户，帐户也不同。 此值可用于执行授权检查（例如，使用令牌访问资源时），并可将它用作数据库表中的键。
tid 字符串，GUID 表示用户登录到的租户。 对于工作和学校帐户，该 GUID 就是用户登录到的组织的不可变租户 ID。 对于登录个人 Microsoft 帐户租户（Xbox、Teams for Life 或 Outlook 等服务）的情况，值为 9188040d-6c67-4c5b-b112-36a304b66dad。 若要接收此声明，应用程序必须请求 profile 范围。 在授权决策中，应考虑将此值与其他声明结合。
unique_name 字符串，仅在 v1.0 令牌中提供 提供一个用户可读值，用于标识令牌使用者。 此值在租户中可能不同，仅将其用于显示目的。
uti 字符串 令牌标识符声明，等效于 JWT 规范中的 jti。 区分大小写的唯一每令牌标识符。
rh 不透明字符串 Azure 用来重新验证令牌的内部声明。 资源不应使用此声明。
ver 字符串，1.0 或 2.0 指示访问令牌的版本。
xms_cc 字符串的 JSON 数组 指示获取令牌的客户端应用程序是否能够处理声明质询。 它经常与声明 acrs 一起使用。 此声明通常用于条件访问和连续访问评估方案。 令牌颁发的资源服务器或服务应用程序可控制令牌中是否存在此声明。 访问令牌中的 cp1 值是确定客户端应用程序能否处理声明质询的权威方式。 有关详细信息，请参阅声明质询、声明请求和客户端功能。

组超额声明

Microsoft Entra ID 会限制它在组声明中包含的对象 ID 数，使其保持在 HTTP 标头的大小限制范围内。 如果用户所属的组数超过超额限制（SAML 令牌的为 150 个，JWT 令牌的为 200 个，通过隐式流颁发的令牌的仅为 6 个），则 Microsoft Entra ID 不会在令牌中发出组声明。 相反，它会在令牌中添加超额声明，指示应用程序查询 Microsoft Graph API 以检索用户的组成员身份。

{
    ...
    "_claim_names": {
        "groups": "src1"
    },
    "_claim_sources": {
        "src1": {
            "endpoint": "[Url to get this user's group membership from]"
        }   
    }
    ...
}

使用应用创建脚本文件夹中提供的 BulkCreateGroups.ps1 可帮助测试超额方案。

注意

返回的 URL 将是 Azure AD 图形 URL（即 graph.windows.net）。 服务应改用 idtyp 可选声明（用于识别令牌是应用还是应用+用户令牌）来构造用于查询组的完整列表 Microsoft Graph URL，而不依赖此 URL。

v1.0 基本声明

v1.0 令牌包括以下声明（如果适用），但默认情况下不包括 v2.0 令牌。 若要将这些声明用于 v2.0，应用程序将使用可选声明来进行请求。

声明 格式 说明
ipaddr String 进行身份验证的用户的来源 IP 地址。
onprem_sid 字符串，采用 SID 格式 如果用户使用了本地身份验证，则此声明会提供其 SID。 在旧版应用程序中将此声明用于授权。
pwd_exp int，Unix 时间戳 指示用户的密码何时过期。
pwd_url 字符串 用户重置其密码的 URL。
in_corp boolean 表示客户端是否从企业网络登录。
nickname 字符串 用户的其他名称，不同于名字或姓氏。
family_name String 根据用户对象中的定义提供用户的姓氏。
given_name 字符串 根据用户对象中的设置提供用户的名字。
upn 字符串 用户的用户名。 可以是电话号码、电子邮件地址或无格式的字符串。 只用于显示目的，在重新身份验证方案中提供用户名提示。

amr 声明

标识可以通过与应用程序相关的多种不同的方式进行身份验证。 amr 声明是可以包含多个项（例如 ["mfa", "rsa", "pwd"]）的数组，用于同时使用密码和Authenticator 应用的身份验证。

值 说明
pwd 密码身份验证，用户的 Microsoft 密码或应用程序的客户端密码。
rsa 身份验证基于 RSA 密钥的证明，例如，使用 Microsoft Authenticator 应用。 此值还指示在身份验证中将自签名 JWT 与服务拥有的 X509 证书配合使用。
otp 使用电子邮件或短信的一次性密码。
fed 指示使用联合身份验证断言（例如 JWT 或 SAML）。
wia Windows 集成身份验证
mfa 指示使用多重身份验证。 包含此声明存在时的其他身份验证方法。
ngcmfa 等效于 mfa，用于预配某些高级凭据类型。
wiaormfa 用户已使用 Windows 或 MFA 凭据进行身份验证。
none 指示没有完成的身份验证。

后续步骤