在 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 读写这些属性。

先决条件

创建自定义属性

  1. 至少以 Azure AD B2C 租户的外部 ID 用户流属性管理员身份登录到 Azure 门户
  2. 如果有权访问多个租户,请选择顶部菜单中的“设置”图标,切换到“目录 + 订阅”菜单中的 Azure AD B2C 租户
  3. 选择 Azure 门户左上角的“所有服务” ,搜索并选择 Azure AD B2C
  4. 选择“用户属性”,然后选择“添加”
  5. 提供自定义属性的“名称”(例如,“ShoeSize”)
  6. 选择“数据类型”。 仅“String”、“Boolean”和“Int”可供选择。
  7. (可选)输入“说明”以供参考。
  8. 选择“创建”。

现在自定义属性在“用户属性”列表中显示,以便在用户流中使用。 自定义属性只在第一次在任何用户流中使用时创建,而不是在添加到用户属性列表时创建。

在用户流中使用自定义属性

  1. 在 Azure AD B2C 租户中,选择“用户流” 。
  2. 选择策略(例如,“B2C_1_SignupSignin”)将其打开。
  3. 选择“用户属性”,然后选择自定义属性(例如,“ShoeSize”)。 选择“保存”。
  4. 选择“应用程序声明”,然后选择自定义属性。
  5. 选择“保存”。

使用用户流创建新用户后,可以使用用户流上的运行用户流功能来验证客户体验。 现在可以在注册期间收集的属性的列表中看到“ShoeSize”,并在发送回应用程序的令牌中看到它。

Azure AD B2C 扩展应用

尽管扩展属性可以包含用户的数据,但它们只能在应用程序对象中注册。 扩展属性会附加到名为 b2c-extensions-app 的应用程序。 请不要修改此应用程序,因为 Azure AD B2C 使用它来存储用户数据。 可以在 Azure AD B2C 应用注册下找到此应用程序。

获取扩展应用的应用程序 ID

  1. 登录 Azure 门户
  2. 如果有权访问多个租户,请选择顶部菜单中的“设置”图标,切换到“目录 + 订阅”菜单中的 Azure AD B2C 租户
  3. 在左侧菜单中,选择“Azure AD B2C”。 或者,选择“所有服务”并搜索并选择“Azure AD B2C”。
  4. 选择“应用注册”,然后选择“所有应用程序” 。
  5. 选择 b2c-extensions-app. Do not modify. Used by AADB2C for storing user data. 应用程序。
  6. 复制“应用程序 ID”。 示例:00001111-aaaa-2222-bbbb-3333cccc4444

获取扩展应用的应用程序属性

  1. 登录 Azure 门户
  2. 如果有权访问多个租户,请选择顶部菜单中的“设置”图标,切换到“目录 + 订阅”菜单中的 Azure AD B2C 租户
  3. 在左侧菜单中,选择“Azure AD B2C”。 或者,选择“所有服务”并搜索并选择“Azure AD B2C”。
  4. 选择“应用注册”,然后选择“所有应用程序” 。
  5. 选择“b2c-extensions-app。不要修改。由 AADB2C 用于存储用户数据。”应用。
  6. 将以下标识符复制到剪贴板并保存:
    • 应用程序 ID。 示例:00001111-aaaa-2222-bbbb-3333cccc4444
    • 对象 ID。 示例:aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb

修改自定义策略

要在策略中启用自定义属性,请提供 AAD-Common 技术配置文件元数据中的应用程序 ID 和应用程序对象 IDAAD-Common 技术配置文件位于基础 Microsoft Entra ID 技术配置文件中,可提供对 Microsoft Entra 用户管理的支持。 其他 Microsoft Entra ID 技术配置文件包括可利用其配置的 AAD-Common。 请替代扩展文件中的 AAD-Common 技术配置文件。

  1. 打开策略的扩展文件, 例如 SocialAndLocalAccounts/TrustFrameworkExtensions.xml

  2. 找到 ClaimsProviders 元素。 向 ClaimsProviders 元素添加一个新的 ClaimsProvider。

  3. 在开头的 <Item Key="ClientId"> 和结尾的 </Item> 元素之间插入之前记录的“应用程序 ID”。

  4. 在开头的 <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: 00001111-aaaa-2222-bbbb-3333cccc4444-->  
              <Item Key="ClientId"></Item>
              <!--Insert b2c-extensions-app application ObjectId here, for example: aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb-->
              <Item Key="ApplicationObjectId"></Item>
            </Metadata>
          </TechnicalProfile>
        </TechnicalProfiles> 
      </ClaimsProvider>
    <!-- 
    </ClaimsProviders> -->
    

上传你的自定义策略

  1. 登录 Azure 门户
  2. 如果有权访问多个租户,请选择顶部菜单中的“设置”图标,从“目录 + 订阅”菜单中切换到你的 Azure AD B2C 租户。
  3. 选择 Azure 门户左上角的“所有服务”,然后搜索并选择“应用注册” 。
  4. 选择“标识体验框架”。
  5. 选择“上传自定义策略”,然后上传你已更改的 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应用程序的 appId11112222-bbbb-3333-cccc-4444dddd5555,且属性名称为loyaltyId,则自定义属性将被命名为extension_25883231668a43a780b25685c3f874bc_loyaltyId

了解如何使用 Microsoft Graph API 管理 Azure AD B2C 租户中的扩展属性

删除扩展属性

与内置属性不同,你可以移除自定义属性。 还可以删除扩展属性的值。

重要

移除自定义属性之前,请将目录中的每个帐户的扩展属性值设置为 null。 这样即可显式删除扩展属性的值。 然后,继续删除扩展属性本身。 自定义属性可以使用 Microsoft Graph API 查询。

使用以下步骤从你的租户的用户流中删除自定义属性:

  1. 至少以 Azure AD B2C 租户的外部 ID 用户流属性管理员身份登录到 Azure 门户
  2. 确保正在使用的目录包含 Azure AD B2C 租户:
    1. 在门户工具栏中选择“目录 + 订阅”图标。
    2. 在“门户设置 | 目录+订阅”页上的“目录名称”列表中,找到你的 Azure AD B2C 目录,然后选择“切换”
  3. 选择 Azure 门户左上角的“所有服务” ,搜索并选择 Azure AD B2C
  4. 选择“用户属性”,然后选择要删除的属性。
  5. 选择“删除”,然后选择“是”进行确认 。

使用 Microsoft Graph API 管理自定义属性。

后续步骤

了解如何使用自定义策略添加声明和自定义用户输入。 此示例使用内置声明“city”。 若要使用自定义属性,请将“city”替换为你自己的自定义属性。