在声明中使用目录架构扩展属性Using directory schema extension attributes in claims

目录架构扩展属性提供了一种方法来存储 Azure Active Directory 中用户对象和其他目录对象(例如组、租户详细信息、服务主体)上的其他数据。Directory schema extension attributes provide a way to store additional data in Azure Active Directory on user objects and other directory objects such as groups, tenant details, service principals. 仅用户对象上的扩展属性可用于向应用程序发出声明。Only extension attributes on user objects can be used for emitting claims to applications. 本文介绍如何在令牌声明中使用目录架构扩展属性将用户数据发送到应用程序。This article describes how to use directory schema extension attributes for sending user data to applications in token claims.

备注

Microsoft Graph 提供了两种可自定义 Graph 对象的其他扩展机制。Microsoft Graph provides two other extension mechanisms to customize Graph objects. 它们分别称为 Microsoft Graph 开启扩展和 Microsoft Graph 架构扩展。These are known as Microsoft Graph open extensions and Microsoft Graph schema extensions. 请参阅 Microsoft Graph 文档以了解详细信息。See the Microsoft Graph documentation for details. 使用这些功能存储在 Microsoft Graph 对象上的数据不能用作令牌中声明的源。Data stored on Microsoft Graph objects using these capabilities are not available as sources for claims in tokens.

目录架构扩展属性始终与租户中的应用程序相关联,并由应用程序的 applicationId 在其名称中引用。Directory schema extension attributes are always associated with an application in the tenant and are referenced by the application's applicationId in their name.

目录架构扩展属性标识符的格式为 Extension_xxxxxxxxx_AttributeName。The identifier for a directory schema extension attribute is of the form Extension_xxxxxxxxx_AttributeName. 其中 xxxxxxxxx 是为其定义扩展的应用程序的 applicationId 。Where xxxxxxxxx is the applicationId of the application the extension was defined for.

注册和使用目录架构扩展Registering and using directory schema extensions

可通过以下两种方式之一注册和填充目录架构扩展属性:Directory schema extension attributes can be registered and populated in one of two ways:

发出包含使用 AD Connect 创建的目录架构扩展属性中数据的声明Emitting claims with data from directory schema extension attributes created with AD Connect

使用 AD Connect 创建和同步的目录架构扩展属性始终与 AD Connect 使用的应用程序 ID 相关联。Directory schema extension attributes created and synced using AD Connect are always associated with the application ID used by AD Connect. 可通过两种方式将其用作声明的源:对于在“企业应用程序”下方使用“库”或“非库”应用程序配置体验注册的 SAML 应用程序,在门户 UI 中“企业应用程序”配置中将其配置为声明;对于通过应用程序注册体验注册的应用程序,通过声明映射策略进行配置。 They can be used as a source for claims both by configuring them as claims in the Enterprise Applications configuration in the Portal UI for SAML applications registered using the Gallery or the non-Gallery application configuration experience under Enterprise Applications , and via a claims-mapping policy for applications registered via the Application registration experience. 通过 AD Connect 创建的目录扩展属性位于目录中之后,它将显示在 SAML SSO 声明配置 UI 中。Once a directory extension attribute created via AD Connect is in the directory, it will show in the SAML SSO claims configuration UI.

使用 Graph 或 PowerShell 发出包含为应用程序所创建目录架构扩展属性中数据的声明Emitting claims with data from directory schema extension attributes created for an application using Graph or PowerShell

如果使用 Microsoft Graph 或 PowerShell 为应用程序注册目录架构扩展属性(例如通过应用程序初始设置或预配步骤),则可以在 Azure Active Directory 中将同一应用程序配置为在用户登录时接收来自声明中的用户对象的该属性中的数据。If a directory schema extension attribute is registered for an application using Microsoft Graph or PowerShell (via an applications initial setup or provisioning step for instance), the same application can be configured in Azure Active Directory to receive data in that attribute from a user object in a claim when the user signs in. 可将应用程序配置为在目录架构扩展中接收数据,该扩展使用可选声明在同一应用程序上进行注册。The application can be configured to receive data in directory schema extensions that are registered on that same application using optional claims. 可以在应用程序清单中设置它们。These can be set in the application manifest. 这使多租户应用程序可以注册目录架构扩展属性以供自己使用。This enables a multi-tenant application to register directory schema extension attributes for its own use. 将应用程序预配到租户中后,相关联的目录架构扩展可以在该租户中的用户上进行设置并可以进行使用。When the application is provisioned into a tenant the associated directory schema extensions become available to be set on users in that tenant, and to be consumed. 在租户中配置该扩展并授予同意后,便可以将其用于通过图形存储和检索数据,以及用于映射令牌中的声明,这些令牌由 Microsoft 标识平台发送到应用程序。Once it's configured in the tenant and consent granted, it can be used to store and retrieve data via graph and to map to claims in tokens Microsoft identity platform emits to applications.

可以为任何应用程序注册和填充目录架构扩展属性。Directory schema extension attributes can be registered and populated for any application.

如果应用程序需要发送声明,该声明具有来自在不同的应用程序上注册的扩展属性的数据,则必须使用声明映射策略将扩展属性映射到声明。If an application needs to send claims with data from an extension attribute registered on a different application, a claims mapping policy must be used to map the extension attribute to the claim. 管理目录架构扩展属性的一种常见模式是创建一个应用程序,该应用程序专门用作所需的所有架构扩展的注册点。A common pattern for managing directory schema extension attributes is to create an application specifically to be the point of registration for all the schema extensions you need. 它不一定是实际的应用程序,且此技术意味着所有扩展在其名称中都具有相同的应用程序 ID。It doesn't have to be a real application and this technique means that all the extensions have the same application ID in their name.

例如,以下声明映射策略用于从 OAuth/OIDC 令牌中的目录架构扩展属性发出单个声明:For example, here is a claims-mapping policy to emit a single claim from a directory schema extension attribute in an OAuth/OIDC token:

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "false",
        "ClaimsSchema": [{
                "Source": "User",
                "ExtensionID": "extension_xxxxxxx_test",
                "JWTClaimType": "http://schemas.contoso.com/identity/claims/exampleclaim"
            },
        ]
    }
}

其中 xxxxxxx 是向其注册扩展的应用程序 ID。Where xxxxxxx is the application ID the extension was registered with.

提示

在对象上设置目录扩展属性时,大小写一致性非常重要。Case consistency is important when setting directory extension attributes on objects. 扩展属性名称在设置时不区分大小写,但在令牌服务从目录读取时区分大小写。Extension attribute names aren't cases sensitive when being set up, but they are case sensitive when being read from the directory by the token service. 如果在名称为“LegacyId”的用户对象和另一个名称为“legacyid”的用户对象上设置了扩展属性,则当使用名称“LegacyId”将属性映射到声明时,将成功检索数据,且声明将包含在第一位用户的令牌中,而不是第二位用户的令牌中。If an extension attribute is set on a user object with the name "LegacyId" and on another user object with the name "legacyid", when the attribute is mapped to a claim using the name "LegacyId" the data will be successfully retrieved and the claim included in the token for the first user but not the second.

用于内置目录属性的声明架构中的“Id”参数是目录扩展属性的“ExtensionID”。The "Id" parameter in the claims schema used for built-in directory attributes is "ExtensionID" for directory extension attributes.

后续步骤Next steps