如何:向应用提供可选声明How to: Provide optional claims to your app

应用程序开发人员可以在其 Azure AD 应用程序中使用可选声明来指定他们希望在发送到其应用程序的令牌中使用哪些声明。Application developers can use optional claims in their Azure AD applications to specify which claims they want in tokens sent to their application.

使用可选声明可以:You can use optional claims to:

  • 选择要包含在应用程序令牌中的附加声明。Select additional claims to include in tokens for your application.
  • 更改 Microsoft 标识平台在令牌中返回的某些声明的行为。Change the behavior of certain claims that Microsoft identity platform returns in tokens.
  • 添加和访问应用程序的自定义声明。Add and access custom claims for your application.

如需标准声明的列表,请参阅访问令牌id_token 声明文档。For the lists of standard claims, see the access token and id_token claims documentation.

尽管在 v1.0 和 v2.0 格式令牌以及 SAML 令牌中都支持可选声明,但在从 v1.0 移动到 v2.0 时,它们提供了其最大值。While optional claims are supported in both v1.0 and v2.0 format tokens, as well as SAML tokens, they provide most of their value when moving from v1.0 to v2.0. v2.0 Microsoft 标识平台终结点的目标之一是减小令牌大小,以确保客户端获得最佳性能。One of the goals of the v2.0 Microsoft identity platform endpoint is smaller token sizes to ensure optimal performance by clients. 因此,以前包含在访问令牌和 ID 令牌中的多个声明不再在 v2.0 令牌中提供,必须根据应用程序专门请求这些声明。As a result, several claims formerly included in the access and ID tokens are no longer present in v2.0 tokens and must be asked for specifically on a per-application basis.

表 1:适用性Table 1: Applicability

帐户类型Account Type v1.0 令牌v1.0 tokens v2.0 令牌v2.0 tokens
Azure AD 帐户Azure AD account 支持Supported 支持Supported

v1.0 和 v2.0 可选声明集v1.0 and v2.0 optional claims set

下面列出了默认可对应用程序使用的可选声明集。The set of optional claims available by default for applications to use are listed below. 若要为应用程序添加自定义可选声明,请参阅下面的目录扩展To add custom optional claims for your application, see Directory Extensions, below. 在向访问令牌添加声明时,这些声明应用到应用程序 (Web API) 请求的访问令牌,而不是应用程序请求的声明。When adding claims to the access token, the claims apply to access tokens requested for the application (a web API), not claims requested by the application. 无论客户端如何访问你的 API,正确的数据都存在于用于对该 API 进行身份验证的访问令牌中。No matter how the client accesses your API, the right data is present in the access token that is used to authenticate against your API.

备注

其中的大多数声明可包含在 v1.0 和 v2.0 令牌的 JWT 中,但不可包含在 SAML 令牌中,“令牌类型”列中指明的声明除外。The majority of these claims can be included in JWTs for v1.0 and v2.0 tokens, but not SAML tokens, except where noted in the Token Type column. 使用者帐户支持部分在“用户类型”列中标记的此类声明。Consumer accounts support a subset of these claims, marked in the "User Type" column. 列出的许多声明不适用于使用者用户(他们没有租户,因此 tenant_ctry 没有值)。Many of the claims listed do not apply to consumer users (they have no tenant, so tenant_ctry has no value).

表 2:v1.0 和 v2.0 可选声明集Table 2: v1.0 and v2.0 optional claim set

名称Name 说明Description 令牌类型Token Type 用户类型User Type 注释Notes
auth_time 用户上次进行身份验证的时间。Time when the user last authenticated. 请参阅 OpenID Connect 规范。See OpenID Connect spec. JWTJWT
tenant_region_scope 资源租户的区域Region of the resource tenant JWTJWT
sid 会话 ID,用于基于会话的用户注销。Session ID, used for per-session user sign-out. JWTJWT Azure AD 帐户。Azure AD accounts.
verified_primary_email 源自用户的 PrimaryAuthoritativeEmailSourced from the user's PrimaryAuthoritativeEmail JWTJWT
verified_secondary_email 源自用户的 SecondaryAuthoritativeEmailSourced from the user's SecondaryAuthoritativeEmail JWTJWT
vnet VNET 说明符信息。VNET specifier information. JWTJWT
fwd IP 地址。IP address. JWTJWT 添加请求方客户端(如果位于 VNET 中)的原始 IPv4 地址Adds the original IPv4 address of the requesting client (when inside a VNET)
ctry 用户所在国家/地区User's country/region JWT、SAMLJWT, SAML Azure AD 返回 ctry 可选声明(如果存在)且此字段的值是标准的双字母国家/地区代码,例如 FR、JP、SZ 等。Azure AD returns the ctry optional claim if it's present and the value of the field is a standard two-letter country/region code, such as FR, JP, SZ, and so on.
tenant_ctry 资源租户所在的国家/地区Resource tenant's country JWTJWT ctry 相同,区别是由管理员在租户级别设置。还必须是标准的双字母值。Same as ctry except set at a tenant level by an admin. Must also be a standard two-letter value.
xms_pdl 首选数据位置Preferred data location JWTJWT 对于多地域租户,首选数据位置是显示用户所在地理区域的三字母代码。For Multi-Geo tenants, the preferred data location is the three-letter code showing the geographic region the user is in.
例如:APC 表示“亚太”。For example: APC for Asia Pacific.
xms_pl 用户首选语言User preferred language JWTJWT 用户的首选语言(如果已设置)。The user's preferred language, if set. 在来宾访问方案中,源自其主租户。Sourced from their home tenant, in guest access scenarios. 已格式化 LL-CC(“zh-cn”)。Formatted LL-CC ("en-us").
xms_tpl 租户首选语言Tenant preferred language JWTJWT 资源租户的首选语言(如果已设置)。The resource tenant's preferred language, if set. 已格式化 LL(“en”)。Formatted LL ("en").
ztdid 零接触部署 IDZero-touch Deployment ID JWTJWT 用于 Windows AutoPilot 的设备标识The device identity used for Windows AutoPilot
email 此用户的可寻址电子邮件(如果此用户有)。The addressable email for this user, if the user has one. JWT、SAMLJWT, SAML MSA、Azure ADMSA, Azure AD 如果用户是租户中的来宾,则默认包含此值。This value is included by default if the user is a guest in the tenant. 对于托管用户(租户内部的用户),它必须通过此可选声明进行请求,或者仅在 v2.0 上使用 OpenID 范围进行请求。For managed users (the users inside the tenant), it must be requested through this optional claim or, on v2.0 only, with the OpenID scope.
acct 租户中的用户帐户状态Users account status in tenant JWT、SAMLJWT, SAML 如果用户是租户的成员,则该值为 0If the user is a member of the tenant, the value is 0. 如果他们是来宾,则该值为 1If they are a guest, the value is 1.
groups 组声明的可选格式Optional formatting for group claims JWT、SAMLJWT, SAML 应用程序清单中的 GroupMembershipClaims 设置(也是必需的)结合使用。Used in conjunction with the GroupMembershipClaims setting in the application manifest, which must be set as well.
upn UserPrincipalNameUserPrincipalName JWT、SAMLJWT, SAML 尽管会自动包含此声明,但可以将它指定为可选声明,以附加额外的属性,在来宾用例中修改此声明的行为。Although this claim is automatically included, you can specify it as an optional claim to attach additional properties to modify its behavior in the guest user case.
idtyp 令牌类型Token type JWT 访问令牌JWT access tokens 特别之处:仅在仅限应用的访问令牌中Special: only in app-only access tokens 当令牌为仅限应用的令牌时,值为 appValue is app when the token is an app-only token. 这是 API 确定令牌是应用令牌还是应用+用户令牌最准确的方法。This is the most accurate way for an API to determine if a token is an app token or an app+user token.

特定于 v2.0 的可选声明集v2.0-specific optional claims set

这些声明始终包含在 v1.0 Azure AD 令牌中,但除非提出请求,否则不会包含在 v2.0 令牌中。These claims are always included in v1.0 Azure AD tokens, but not included in v2.0 tokens unless requested. 这些声明仅适用于 JWT(ID 令牌和访问令牌)。These claims are only applicable for JWTs (ID tokens and Access Tokens).

表 3:仅限 v2.0 的可选声明Table 3: v2.0-only optional claims

JWT 声明JWT Claim 名称Name 说明Description 说明Notes
ipaddr IP 地址IP Address 客户端从中登录的 IP 地址。The IP address the client logged in from.
onprem_sid 本地安全标识符On-Premises Security Identifier
pwd_exp 密码过期时间Password Expiration Time 密码过期的日期时间。The datetime at which the password expires.
pwd_url 更改密码 URLChange Password URL 用户更改密码时可以访问的 URL。A URL that the user can visit to change their password.
in_corp 企业网络内部Inside Corporate Network 表示客户端是否从企业网络登录。Signals if the client is logging in from the corporate network. 如果不是,则不包括该声明。If they're not, the claim isn't included. 以 MFA 中的可信 IP 设置为基础。Based off of the trusted IPs settings in MFA.
family_name 姓氏Last Name 根据用户对象中的定义提供用户的姓氏。Provides the last name, surname, or family name of the user as defined in the user object.
"family_name":"Miller""family_name":"Miller"
在 MSA 和 Azure AD 中受支持。Supported in MSA and Azure AD. 需要 profile 范围。Requires the profile scope.
given_name 名字First name 根据用户对象中的设置提供用户的名字和“姓氏”。Provides the first or "given" name of the user, as set on the user object.
"given_name":"Frank""given_name": "Frank"
在 MSA 和 Azure AD 中受支持。Supported in MSA and Azure AD . 需要 profile 范围。Requires the profile scope.
upn 用户主体名称User Principal Name 可以与 username_hint 参数一起使用的用户标识符。An identifer for the user that can be used with the username_hint parameter. 不是用户的持久标识符,不应当用于关键数据。Not a durable identifier for the user and should not be used to key data. 有关声明配置,请参阅下面的附加属性See additional properties below for configuration of the claim. 需要 profile 范围。Requires the profile scope.

可选声明的附加属性Additional properties of optional claims

可以配置某些可选声明来更改声明的返回方式。Some optional claims can be configured to change the way the claim is returned. 这些附加属性主要用于帮助迁移具有不同数据预期的本地应用程序(例如,include_externally_authenticated_upn_without_hash 可帮助迁移无法处理 UPN 中的井号标记 (#) 的客户端)These additional properties are mostly used to help migration of on-premises applications with different data expectations (for example, include_externally_authenticated_upn_without_hash helps with clients that cannot handle hash marks (#) in the UPN)

表 4:用于配置可选声明的值Table 4: Values for configuring optional claims

属性名称Property name 附加属性名称Additional Property name 说明Description
upn 可用于 SAML 和 JWT 响应,以及 v1.0 和 v2.0 令牌。Can be used for both SAML and JWT responses, and for v1.0 and v2.0 tokens.
include_externally_authenticated_upn 包含资源租户中存储的来宾 UPN。Includes the guest UPN as stored in the resource tenant. 例如: foo_hometenant.com#EXT#@resourcetenant.comFor example, foo_hometenant.com#EXT#@resourcetenant.com
include_externally_authenticated_upn_without_hash 同上,不过,井号标记 (#) 已替换为下划线 (_),例如 foo_hometenant.com_EXT_@resourcetenant.comSame as above, except that the hash marks (#) are replaced with underscores (_), for example foo_hometenant.com_EXT_@resourcetenant.com

附加属性示例Additional properties example

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

此 OptionalClaims 对象会导致返回到客户端的 ID 令牌包含一个 upn 声明及其他主租户和资源租户信息。This OptionalClaims object causes the ID token returned to the client to include a upn claim with the additional home tenant and resource tenant information. 仅当用户是租户中的来宾(使用不同的 IDP 进行身份验证)时,才会更改令牌中的 upn 声明。The upn claim is only changed in the token if the user is a guest in the tenant (that uses a different IDP for authentication).

配置可选声明Configuring optional claims

重要

访问令牌始终使用资源清单而不是客户端生成。Access tokens are always generated using the manifest of the resource, not the client. 因此,在请求 ...scope=https://microsoftgraph.chinacloudapi.cn/user.read... 中,资源是 Microsoft Graph API。So in the request ...scope=https://microsoftgraph.chinacloudapi.cn/user.read... the resource is the Microsoft Graph API. 因此,访问令牌是使用 Microsoft Graph API 清单而不是客户端清单创建的。Thus, the access token is created using the Microsoft Graph API manifest, not the client's manifest. 更改应用程序的清单从不会导致 Microsoft Graph API 的令牌看起来有何不同。Changing the manifest for your application will never cause tokens for the Microsoft Graph API to look different. 为了验证 accessToken 更改是否有效,请为你的应用程序请求一个令牌,而不是其他应用。In order to validate that your accessToken changes are in effect, request a token for your application, not another app.

可以通过 UI 或应用程序清单来配置应用程序的可选声明。You can configure optional claims for your application through the UI or application manifest.

  1. 转到 Azure 门户Go to the Azure portal. 搜索并选择“Azure Active Directory”。Search for and select Azure Active Directory.
  2. 从“管理”部分中选择“应用注册” 。From the Manage section, select App registrations.
  3. 在列表中选择要为其配置可选声明的应用程序。Select the application you want to configure optional claims for in the list.

通过 UI 配置可选声明:Configuring optional claims through the UI:

演示如何使用 UI 配置可选声明Shows how to configure optional claims using the UI

  1. 从“管理”部分中选择“令牌配置” 。From the Manage section, select Token configuration.
  2. 选择“添加可选声明”。Select Add optional claim.
  3. 选择要配置的令牌类型。Select the token type you want to configure.
  4. 选择要添加的可选声明。Select the optional claims to add.
  5. 选择 添加Select Add.

通过应用程序清单配置可选声明:Configuring optional claims through the application manifest:

演示如何使用应用清单配置可选声明Shows how to configure optional claims using the app manifest

  1. 在“管理”部分,选择“清单”。 From the Manage section, select Manifest. 此时会打开一个基于 Web 的清单编辑器,可在其中编辑清单。A web-based manifest editor opens, allowing you to edit the manifest. (可选)可以选择“下载”并在本地编辑清单,然后使用“上传”将清单重新应用到应用程序。 Optionally, you can select Download and edit the manifest locally, and then use Upload to reapply it to your application. 有关应用程序清单的详细信息,请参阅了解 Azure AD 应用程序清单一文。For more information on the application manifest, see the Understanding the Azure AD application manifest article.

    以下应用程序清单条目将 auth_time、ipaddr 和 upn 可选声明添加到 ID、访问和 SAML 令牌。The following application manifest entry adds the auth_time, ipaddr, and upn optional claims to ID, access, and SAML tokens.

    "optionalClaims": {
        "idToken": [
            {
                "name": "auth_time",
                "essential": false
            }
        ],
        "accessToken": [
            {
                "name": "ipaddr",
                "essential": false
            }
        ],
        "saml2Token": [
            {
                "name": "upn",
                "essential": false
            },
            {
                "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
                "source": "user",
                "essential": false
            }
        ]
    }
    
  2. 完成后,选择“保存”。When finished, select Save. 现在,指定的可选声明将包含在应用程序的令牌中。Now the specified optional claims will be included in the tokens for your application.

OptionalClaims 类型OptionalClaims type

声明应用程序请求的可选声明。Declares the optional claims requested by an application. 应用程序可以配置可选声明,以在它能够从安全令牌服务收到的每种令牌(共三种,即 ID 令牌、访问令牌、SAML 令牌)中返回。An application can configure optional claims to be returned in each of three types of tokens (ID token, access token) it can receive from the security token service. 应用程序可以配置为要在每种令牌类型中返回一组不同的可选声明。The application can configure a different set of optional claims to be returned in each token type. Application 实体的 OptionalClaims 属性是一个 OptionalClaims 对象。The OptionalClaims property of the Application entity is an OptionalClaims object.

表 5:OptionalClaims 类型属性Table 5: OptionalClaims type properties

名称Name 类型Type 说明Description
idToken 集合 (OptionalClaim)Collection (OptionalClaim) 在 JWT ID 令牌中返回的可选声明。The optional claims returned in the JWT ID token.
accessToken 集合 (OptionalClaim)Collection (OptionalClaim) 在 JWT 访问令牌中返回的可选声明。The optional claims returned in the JWT access token.
saml2Token 集合 (OptionalClaim)Collection (OptionalClaim) 在 SAML 令牌中返回的可选声明。The optional claims returned in the SAML token.

OptionalClaim 类型OptionalClaim type

包含与应用程序或服务主体关联的可选声明。Contains an optional claim associated with an application or a service principal. OptionalClaims 类型的 IdToken、accessToken 和 saml2Token 属性是一个 OptionalClaim 集合。The idToken, accessToken, and saml2Token properties of the OptionalClaims type is a collection of OptionalClaim. 如果特定的声明支持这样做,则还可以使用 AdditionalProperties 字段修改 OptionalClaim 的行为。If supported by a specific claim, you can also modify the behavior of the OptionalClaim using the AdditionalProperties field.

表 6:OptionalClaim 类型属性Table 6: OptionalClaim type properties

名称Name 类型Type 说明Description
name Edm.StringEdm.String 可选声明的名称。The name of the optional claim.
source Edm.StringEdm.String 声明的源(目录对象)。The source (directory object) of the claim. 扩展属性提供预定义声明和用户定义的声明。There are predefined claims and user-defined claims from extension properties. 如果源值为 null,则声明是预定义的可选声明。If the source value is null, the claim is a predefined optional claim. 如果源值为 user,则 name 属性中的值是来自用户对象的扩展属性。If the source value is user, the value in the name property is the extension property from the user object.
essential Edm.BooleanEdm.Boolean 如果值为 true,则必须使用客户端指定的声明,以确保为最终用户请求的特定任务提供顺利的授权体验。If the value is true, the claim specified by the client is necessary to ensure a smooth authorization experience for the specific task requested by the end user. 默认值是 False。The default value is false.
additionalProperties 集合 (Edm.String)Collection (Edm.String) 声明的附加属性。Additional properties of the claim. 如果此集合中存在某个属性,该属性将修改 name 属性中指定的可选声明的行为。If a property exists in this collection, it modifies the behavior of the optional claim specified in the name property.

配置目录扩展可选声明Configuring directory extension optional claims

除了标准的可选声明集外,还可以将令牌配置为包括扩展。In addition to the standard optional claims set, you can also configure tokens to include extensions. 有关详细信息,请参阅 Microsoft Graph extensionProperty 文档For more info, see the Microsoft Graph extensionProperty documentation.

可选声明不支持架构和开放扩展,仅支持 AAD-Graph 样式的目录扩展。Schema and open extensions are not supported by optional claims, only the AAD-Graph style directory extensions. 使用此功能可以附加应用可以使用的附加用户信息 - 例如,用户设置的附加标识符或重要配置选项。This feature is useful for attaching additional user information that your app can use - for example, an additional identifier or important configuration option that the user has set. 参阅此页面底部的示例。See the bottom of this page for an example.

备注

目录架构扩展功能只能在 AAD 中使用。Directory schema extensions are an Azure AD-only feature. 如果应用程序清单请求自定义扩展,而 MSA 用户登录到你的应用,则不会返回这些扩展。If your application manifest requests a custom extension and an MSA user logs in to your app, these extensions will not be returned.

目录扩展格式Directory extension formatting

使用应用程序清单配置目录扩展可选声明时,请使用扩展的完整名称(格式为:extension_<appid>_<attributename>)。When configuring directory extension optional claims using the application manifest, use the full name of the extension (in the format: extension_<appid>_<attributename>). <appid> 必须与请求该声明的应用程序的 ID 相匹配。The <appid> must match the ID of the application requesting the claim.

在 JWT 中,将使用以下命名格式发出这些声明:extn.<attributename>Within the JWT, these claims will be emitted with the following name format: extn.<attributename>.

在 SAML 令牌中,将使用以下 URI 格式发出这些声明:http://schemas.microsoft.com/identity/claims/extn.<attributename>Within the SAML tokens, these claims will be emitted with the following URI format: http://schemas.microsoft.com/identity/claims/extn.<attributename>

配置组可选声明Configuring groups optional claims

备注

为从本地同步的用户和组发出组名的功能目前为公共预览版。The ability to emit group names for users and groups synced from on-premises is Public Preview.

本部分介绍可选声明下的配置选项,这些选项可将组声明中使用的组特性从默认的组 objectID 更改为从本地 Windows Active Directory 同步的特性。This section covers the configuration options under optional claims for changing the group attributes used in group claims from the default group objectID to attributes synced from on-premises Windows Active Directory. 可以通过 UI 或应用程序清单为应用程序配置组可选声明。You can configure groups optional claims for your application through the UI or application manifest.

通过 UI 配置组可选声明:Configuring groups optional claims through the UI:

  1. 登录到 Azure 门户Sign in to the Azure portal
  2. 通过身份验证后,在页面右上角选择 Azure AD 租户After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page
  3. 在左侧菜单中,选择“Azure Active Directory”Select Azure Active Directory from the left-hand menu
  4. 在“管理”部分下,选择“应用注册” Under the Manage section, select App registrations
  5. 在列表中选择要为其配置可选声明的应用程序Select the application you want to configure optional claims for in the list
  6. 在“管理”部分下,选择“令牌配置” Under the Manage section, select Token configuration
  7. 选择“添加组声明”Select Add groups claim
  8. 选择要返回的组类型(“所有组”、“SecurityGroup”或“DirectoryRole”)。 Select the group types to return (All Groups, SecurityGroup, or DirectoryRole). “所有组”选项包括“SecurityGroup”、“DirectoryRole”和“DistributionList” The All Groups option includes SecurityGroup, DirectoryRole, and DistributionList
  9. 可选:选择特定的令牌类型属性,将组声明值修改为包含本地组特性,或将声明类型更改为角色Optional: select the specific token type properties to modify the groups claim value to contain on premises group attributes or to change the claim type to a role
  10. 选择“保存”Select Save

通过应用程序清单配置组可选声明:Configuring groups optional claims through the application manifest:

  1. 登录到 Azure 门户Sign in to the Azure portal

  2. 通过身份验证后,在页面右上角选择 Azure AD 租户After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page

  3. 在左侧菜单中,选择“Azure Active Directory”Select Azure Active Directory from the left-hand menu

  4. 在列表中选择要为其配置可选声明的应用程序Select the application you want to configure optional claims for in the list

  5. 在“管理”部分下,选择“清单” Under the Manage section, select Manifest

  6. 使用清单编辑器添加以下条目:Add the following entry using the manifest editor:

    有效值为:The valid values are:

    • “所有”(此选项包括 SecurityGroup、DirectoryRole 和 DistributionList)"All" (this option includes SecurityGroup, DirectoryRole, and DistributionList)
    • "SecurityGroup""SecurityGroup"
    • "DirectoryRole""DirectoryRole"

    例如:For example:

    "groupMembershipClaims": "SecurityGroup"
    

    默认情况下,将在组声明值中发出组 ObjectID。By default Group ObjectIDs will be emitted in the group claim value. 若要将声明值修改为包含本地组特性,或者要将声明类型更改为角色,请按如下所示使用 OptionalClaims 配置:To modify the claim value to contain on premises group attributes, or to change the claim type to role, use OptionalClaims configuration as follows:

  7. 设置组名配置可选声明。Set group name configuration optional claims.

    如果希望令牌中的组包含“可选声明”节中的本地 AD 组特性,请指定要应用到的令牌类型可选声明、请求的可选声明的名称,以及所需的任何其他属性。If you want to groups in the token to contain the on premises AD group attributes in the optional claims section specify which token type optional claim should be applied to, the name of optional claim requested and any additional properties desired. 可以列出多个令牌类型:Multiple token types can be listed:

    • OIDC ID 令牌的 idTokenidToken for the OIDC ID token
    • OAuth 访问令牌的 accessTokenaccessToken for the OAuth access token
    • SAML 令牌的 Saml2Token。Saml2Token for SAML tokens.

    备注

    Saml2Token 类型将应用到 SAML1.1 和 SAML2.0 格式令牌The Saml2Token type applies to both SAML1.1 and SAML2.0 format tokens

    对于每个相关的令牌类型,请修改组声明以在清单中使用 OptionalClaims 节。For each relevant token type, modify the groups claim to use the OptionalClaims section in the manifest. OptionalClaims 架构如下所示:The OptionalClaims schema is as follows:

    {
        "name": "groups",
        "source": null,
        "essential": false,
        "additionalProperties": []
    }
    
    可选声明架构Optional claims schema Value
    name:name: 必须是“groups”Must be "groups"
    source:source: 未使用。Not used. 省略或指定 nullOmit or specify null
    essential:essential: 未使用。Not used. 省略或指定 falseOmit or specify false
    additionalProperties:additionalProperties: 附加属性列表。List of additional properties. 有效选项为“sam_account_name”、“dns_domain_and_sam_account_name”、“netbios_domain_and_sam_account_name”、“emit_as_roles”Valid options are "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "emit_as_roles"

    在 additionalProperties 中,只需要指定“sam_account_name”、“dns_domain_and_sam_account_name”和“netbios_domain_and_sam_account_name”中的一个。In additionalProperties only one of "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name" are required. 如果存在多个,则将使用第一个,而忽略其他。If more than one is present, the first is used and any others ignored.

    某些应用程序需要角色声明中有关用户的组信息。Some applications require group information about the user in the role claim. 要将声明类型从组声明更改为角色声明,请将“emit_as_roles”添加到附加属性。To change the claim type to from a group claim to a role claim, add "emit_as_roles" to additional properties. 组值将在角色声明中发出。The group values will be emitted in the role claim.

    备注

    如果使用“emit_as_roles”,则分配了用户的任何已配置应用程序角色不会显示在角色声明中If "emit_as_roles" is used any Application Roles configured that the user is assigned will not appear in the role claim

示例:Examples:

  1. 在 OAuth 访问令牌中以 dnsDomainName\sAMAccountName 格式的组名发出组Emit groups as group names in OAuth access tokens in dnsDomainName\sAMAccountName format

    UI 配置:UI configuration:

    演示如何使用 UI 配置可选声明Shows how to configure optional claims using the UI

    应用程序清单条目:Application manifest entry:

    "optionalClaims": {
        "accessToken": [
            {
                "name": "groups",
                "additionalProperties": [
                    "dns_domain_and_sam_account_name"
                ]
            }
        ]
    }
    
  2. 发出要以 netbiosDomain\sAMAccountName 格式返回的组名,作为 SAML 和 OIDC ID 令牌中的角色声明Emit group names to be returned in netbiosDomain\sAMAccountName format as the roles claim in SAML and OIDC ID Tokens

    UI 配置:UI configuration:

    演示如何使用 UI 配置可选声明Shows how to configure optional claims using the UI

    应用程序清单条目:Application manifest entry:

    "optionalClaims": {
        "saml2Token": [
            {
                "name": "groups",
                "additionalProperties": [
                    "netbios_name_and_sam_account_name",
                    "emit_as_roles"
                ]
            }
        ],
        "idToken": [
            {
                "name": "groups",
                "additionalProperties": [
                    "netbios_name_and_sam_account_name",
                    "emit_as_roles"
                ]
            }
        ]
    }
    

可选声明示例Optional claims example

本部分通过一个场景来演练如何对应用程序使用可选声明功能。In this section, you can walk through a scenario to see how you can use the optional claims feature for your application. 可以使用多个选项来更新应用程序标识配置中的属性,以启用和配置可选声明:There are multiple options available for updating the properties on an application's identity configuration to enable and configure optional claims:

示例:Example:

以下示例使用“令牌配置”UI 和“清单”将可选声明添加到用于应用程序的访问令牌、ID 令牌和 SAML 令牌 。In the example below, you will use the Token configuration UI and Manifest to add optional claims to the access, ID, and SAML tokens intended for your application. 不同的可选声明将添加到应用程序可以接收的每种令牌:Different optional claims will be added to each type of token that the application can receive:

  • ID 令牌现在会包含联合用户的完整格式 UPN (<upn>_<homedomain>#EXT#@<resourcedomain>)。The ID tokens will now contain the UPN for federated users in the full form (<upn>_<homedomain>#EXT#@<resourcedomain>).
  • 其他客户端请求此应用程序的访问令牌现在将包含 auth_time 声明The access tokens that other clients request for this application will now include the auth_time claim
  • SAML 令牌现在会包含 skypeId 目录架构扩展(在本例中,此应用的应用 ID 为 ab603c56068041afb2f6832e2a17e237)。The SAML tokens will now contain the skypeId directory schema extension (in this example, the app ID for this app is ab603c56068041afb2f6832e2a17e237). SAML 令牌会将 Skype ID 公开为 extension_skypeIdThe SAML tokens will expose the Skype ID as extension_skypeId.

UI 配置:UI configuration:

  1. 登录到 Azure 门户Sign in to the Azure portal

  2. 通过身份验证后,在页面右上角选择 Azure AD 租户。After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. 从左侧菜单中选择“Azure Active Directory”。Select Azure Active Directory from the left-hand menu.

  4. 在“管理”部分下选择“应用注册” 。Under the Manage section, select App registrations.

  5. 在列表中找到要为其配置可选声明的应用程序并选择它。Find the application you want to configure optional claims for in the list and select it.

  6. 在“管理”部分下,选择“令牌配置” 。Under the Manage section, select Token configuration.

  7. 选择“添加可选声明”,选择 ID 令牌类型,从声明列表中选择 upn,然后选择“添加” 。Select Add optional claim, select the ID token type, select upn from the list of claims, and then select Add.

  8. 选择“添加可选声明”,选择“访问”令牌类型,从声明列表中选择 auth_time,然后选择“添加” 。Select Add optional claim, select the Access token type, select auth_time from the list of claims, then select Add.

  9. 在“令牌配置”概览屏幕中,选择 upn 旁边的铅笔图标,选择“外部身份验证”切换开关,然后选择“保存” 。From the Token Configuration overview screen, select the pencil icon next to upn, select the Externally authenticated toggle, and then select Save.

  10. 选择“添加可选声明”,选择 SAML 令牌类型,从声明列表中选择 extn.skypeID(仅当创建了名为 skypeID 的 Azure AD 用户对象时才适用),然后选择“添加” 。Select Add optional claim, select the SAML token type, select extn.skypeID from the list of claims (only applicable if you've created an Azure AD user object called skypeID), and then select Add.

    演示如何使用 UI 配置可选声明Shows how to configure optional claims using the UI

清单配置:Manifest configuration:

  1. 登录 Azure 门户Sign in to the Azure portal.

  2. 通过身份验证后,在页面右上角选择 Azure AD 租户。After you've authenticated, choose your Azure AD tenant by selecting it from the top-right corner of the page.

  3. 从左侧菜单中选择“Azure Active Directory”。Select Azure Active Directory from the left-hand menu.

  4. 在列表中找到要为其配置可选声明的应用程序并选择它。Find the application you want to configure optional claims for in the list and select it.

  5. 在“管理”部分下,选择“清单”打开内联的清单编辑器 。Under the Manage section, select Manifest to open the inline manifest editor.

  6. 可使用此编辑器直接编辑清单。You can directly edit the manifest using this editor. 该清单遵循 Application 实体的架构,保存后会自动设置格式。The manifest follows the schema for the Application entity, and automatically formats the manifest once saved. 新元素将添加到 OptionalClaims 属性。New elements will be added to the OptionalClaims property.

    "optionalClaims": {
        "idToken": [
            {
                "name": "upn",
                "essential": false,
                "additionalProperties": [
                    "include_externally_authenticated_upn"
                ]
            }
        ],
        "accessToken": [
            {
                "name": "auth_time",
                "essential": false
            }
        ],
        "saml2Token": [
            {
                "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
                "source": "user",
                "essential": true
            }
        ]
    }
    
  7. 更新完清单后,选择“保存”以保存清单。When you're finished updating the manifest, select Save to save the manifest.

后续步骤Next steps

详细了解 Azure AD 提供的标准声明。Learn more about the standard claims provided by Azure AD.