在 Azure Active Directory B2C 中定义自定义属性
开始之前,请使用此页顶部的“选择策略类型”选择器来选择要设置的策略类型。 Azure Active Directory B2C 提供了两种定义用户如何与应用程序交互的方法:通过预定义的用户流,或者通过可完全配置的自定义策略。 对于每种方法,本文中所需的步骤都不同。
在使用自定义策略添加声明和自定义用户输入一文中,你将了解如何使用内置用户配置文件属性。 在本文中,你将在 Azure Active Directory B2C (Azure AD B2C) 目录中启用一个自定义属性。 稍后,你可以将该新属性同时用作多个用户流或自定义策略中的自定义声明。
Azure AD B2C 目录附带了一组内置属性。 但是,你通常需要创建自己的属性来管理你的特定方案,例如,在以下情况下:
- 面向客户的应用程序需要持久保存 loyaltyId 属性。
- 标识提供者具有必须持久保存的唯一用户标识符 uniqueUserGUID。
- 自定义用户旅程需要持久保存用户的状态 migrationStatus,以便其他逻辑基于该状态运行。
术语扩展属性、自定义属性和自定义声明在本文的上下文中引用相同的内容。 名称会因上下文(应用程序、对象、策略)而异。
Azure AD B2C 允许你扩展存储在每个用户帐户中的属性集。 还可以使用 Microsoft Graph API 读写这些属性。
先决条件
- 创建用户流,以便用户能够注册并登录应用程序。
- 注册 Web 应用程序。
- 完成 Active Directory B2C 中的自定义策略入门中的步骤。 本教程指导你如何更新自定义策略文件以使用 Azure AD B2C 租户配置。
- 注册 Web 应用程序。
创建自定义属性
- 至少以 Azure AD B2C 租户的外部 ID 用户流属性管理员身份登录到 Azure 门户。
- 如果有权访问多个租户,请选择顶部菜单中的“设置”图标,切换到“目录 + 订阅”菜单中的 Azure AD B2C 租户。
- 选择 Azure 门户左上角的“所有服务” ,搜索并选择 Azure AD B2C。
- 选择“用户属性”,然后选择“添加”。
- 提供自定义属性的“名称”(例如,“ShoeSize”)
- 选择“数据类型”。 仅“String”、“Boolean”和“Int”可供选择。
- (可选)输入“说明”以供参考。
- 选择“创建”。
现在自定义属性在“用户属性”列表中显示,以便在用户流中使用。 自定义属性只在第一次在任何用户流中使用时创建,而不是在添加到用户属性列表时创建。
在用户流中使用自定义属性
- 在 Azure AD B2C 租户中,选择“用户流” 。
- 选择策略(例如,“B2C_1_SignupSignin”)将其打开。
- 选择“用户属性”,然后选择自定义属性(例如,“ShoeSize”)。 选择“保存”。
- 选择“应用程序声明”,然后选择自定义属性。
- 选择“保存”。
使用用户流创建新用户后,可以使用用户流上的运行用户流功能来验证客户体验。 现在可以在注册期间收集的属性的列表中看到“ShoeSize”,并在发送回应用程序的令牌中看到它。
Azure AD B2C 扩展应用
尽管扩展属性可以包含用户的数据,但它们只能在应用程序对象中注册。 扩展属性会附加到名为 b2c-extensions-app
的应用程序。 请不要修改此应用程序,因为 Azure AD B2C 使用它来存储用户数据。 可以在 Azure AD B2C 应用注册下找到此应用程序。
获取扩展应用的应用程序 ID
- 登录 Azure 门户。
- 如果有权访问多个租户,请选择顶部菜单中的“设置”图标,切换到“目录 + 订阅”菜单中的 Azure AD B2C 租户。
- 在左侧菜单中,选择“Azure AD B2C”。 或者,选择“所有服务”并搜索并选择“Azure AD B2C”。
- 选择“应用注册”,然后选择“所有应用程序” 。
- 选择
b2c-extensions-app. Do not modify. Used by AADB2C for storing user data.
应用程序。 - 复制“应用程序 ID”。 示例:
11111111-1111-1111-1111-111111111111
。
获取扩展应用的应用程序属性
- 登录 Azure 门户。
- 如果有权访问多个租户,请选择顶部菜单中的“设置”图标,切换到“目录 + 订阅”菜单中的 Azure AD B2C 租户。
- 在左侧菜单中,选择“Azure AD B2C”。 或者,选择“所有服务”并搜索并选择“Azure AD B2C”。
- 选择“应用注册”,然后选择“所有应用程序” 。
- 选择“b2c-extensions-app。不要修改。由 AADB2C 用于存储用户数据。”应用。
- 将以下标识符复制到剪贴板并保存:
- 应用程序 ID。 示例:
11111111-1111-1111-1111-111111111111
。 - 对象 ID。 示例:
22222222-2222-2222-2222-222222222222
。
- 应用程序 ID。 示例:
修改自定义策略
要在策略中启用自定义属性,请提供 AAD-Common 技术配置文件元数据中的应用程序 ID 和应用程序对象 ID。 AAD-Common 技术配置文件位于基础 Microsoft Entra ID 技术配置文件中,可提供对 Microsoft Entra 用户管理的支持。 其他 Microsoft Entra ID 技术配置文件包括可利用其配置的 AAD-Common。 请替代扩展文件中的 AAD-Common 技术配置文件。
打开策略的扩展文件, 例如
SocialAndLocalAccounts/
TrustFrameworkExtensions.xml
。找到 ClaimsProviders 元素。 向 ClaimsProviders 元素添加一个新的 ClaimsProvider。
在开头的
<Item Key="ClientId">
和结尾的</Item>
元素之间插入之前记录的“应用程序 ID”。在开头的
<Item Key="ApplicationObjectId">
和结尾的</Item>
元素之间插入之前记录的“应用程序 ObjectID”。<!-- <ClaimsProviders> --> <ClaimsProvider> <DisplayName>Azure Active Directory</DisplayName> <TechnicalProfiles> <TechnicalProfile Id="AAD-Common"> <Metadata> <!--Insert b2c-extensions-app application ID here, for example: 11111111-1111-1111-1111-111111111111--> <Item Key="ClientId"></Item> <!--Insert b2c-extensions-app application ObjectId here, for example: 22222222-2222-2222-2222-222222222222--> <Item Key="ApplicationObjectId"></Item> </Metadata> </TechnicalProfile> </TechnicalProfiles> </ClaimsProvider> <!-- </ClaimsProviders> -->
上传你的自定义策略
- 登录 Azure 门户。
- 如果有权访问多个租户,请选择顶部菜单中的“设置”图标,从“目录 + 订阅”菜单中切换到你的 Azure AD B2C 租户。
- 选择 Azure 门户左上角的“所有服务”,然后搜索并选择“应用注册” 。
- 选择“标识体验框架”。
- 选择“上传自定义策略”,然后上传你已更改的 TrustFrameworkExtensions.xml 策略文件。
注意
Microsoft Entra ID 技术配置文件首次将声明保存到目录时,会检查自定义属性是否存在。 如果不存在,它会创建自定义属性。
通过 Azure 门户创建自定义属性
内置策略和自定义策略共享相同的扩展属性。 通过门户体验添加自定义属性时,使用每个 B2C 租户中都存在的 b2c-extensions-app 注册这些属性。
在自定义策略中使用这些属性之前或之后,你可以使用门户 UI 创建它们。 在门户中创建属性 loyaltyId 时,必须对其进行引用,如下所示:
名称 | 适用范围 |
---|---|
extension_loyaltyId |
自定义策略 |
extension_<b2c-extensions-app-guid>_loyaltyId |
Microsoft 图形 API |
注意
在自定义策略中使用自定义属性时,必须在声明类型 ID 前加上 extension_
,以允许在 Azure AD B2C 目录中进行正确的数据映射。
下面的示例演示了如何在 Azure AD B2C 自定义策略声明定义中使用自定义属性。
<BuildingBlocks>
<ClaimsSchema>
<ClaimType Id="extension_loyaltyId">
<DisplayName>Loyalty Identification</DisplayName>
<DataType>string</DataType>
<UserHelpText>Your loyalty number from your membership card</UserHelpText>
<UserInputType>TextBox</UserInputType>
</ClaimType>
</ClaimsSchema>
</BuildingBlocks>
下面的示例演示了如何在 Azure AD B2C 自定义策略的技术配置文件、输入声明、输出声明和持久性声明中使用自定义属性。
<InputClaims>
<InputClaim ClaimTypeReferenceId="extension_loyaltyId" />
</InputClaims>
<PersistedClaims>
<PersistedClaim ClaimTypeReferenceId="extension_loyaltyId" />
</PersistedClaims>
<OutputClaims>
<OutputClaim ClaimTypeReferenceId="extension_loyaltyId" />
</OutputClaims>
通过 Microsoft Graph 管理扩展属性
可以使用 Microsoft Graph 创建和管理自定义属性,然后为用户设置值。 扩展属性也称为目录或 Microsoft Entra 扩展。
Microsoft Graph API 中的自定义属性(目录扩展)使用约定 extension_{appId-without-hyphens}_{extensionProperty-name}
命名,其中 {appId-without-hyphens}
是 appId 的精简版(在 Azure AD B2C 门户中称为客户端 ID),因为 b2c-extensions-app
仅包含字符 0-9 和 A-Z。 例如,如果b2c-extensions-app
应用程序的 appId 为25883231-668a-43a7-80b2-5685c3f874bc
,且属性名称为loyaltyId
,则自定义属性将被命名为extension_25883231668a43a780b25685c3f874bc_loyaltyId
。
了解如何使用 Microsoft Graph API 管理 Azure AD B2C 租户中的扩展属性。
删除扩展属性
与内置属性不同,你可以移除自定义属性。 还可以删除扩展属性的值。
重要
移除自定义属性之前,请将目录中的每个帐户的扩展属性值设置为 null
。 这样即可显式删除扩展属性的值。 然后,继续删除扩展属性本身。 自定义属性可以使用 Microsoft Graph API 查询。
使用以下步骤从你的租户的用户流中删除自定义属性:
- 至少以 Azure AD B2C 租户的外部 ID 用户流属性管理员身份登录到 Azure 门户。
- 确保正在使用的目录包含 Azure AD B2C 租户:
- 在门户工具栏中选择“目录 + 订阅”图标。
- 在“门户设置 | 目录+订阅”页上的“目录名称”列表中,找到你的 Azure AD B2C 目录,然后选择“切换”
- 选择 Azure 门户左上角的“所有服务” ,搜索并选择 Azure AD B2C。
- 选择“用户属性”,然后选择要删除的属性。
- 选择“删除”,然后选择“是”进行确认 。
使用 Microsoft Graph API 管理自定义属性。
后续步骤
了解如何使用自定义策略添加声明和自定义用户输入。 此示例使用内置声明“city”。 若要使用自定义属性,请将“city”替换为你自己的自定义属性。