显示控件

项目
2025/05/18

重要

自 2025 年 5 月 1 日起，Azure AD B2C 将不再可供新客户购买。在我们的常见问题解答中了解详细信息。

备注

在 Azure Active Directory B2C 中，自定义策略主要用于解决复杂场景。对于大多数场景，我们建议您使用内置的用户流。如果未这样做，请通过 Active Directory B2C 中的自定义策略入门来了解自定义策略初学者包。

显示控件是具有特殊功能的用户界面元素，可与 Azure Active Directory B2C （Azure AD B2C）后端服务交互。它允许用户在后端调用验证技术配置文件的页面上执行作。显示控件显示在页面上，并由自断言技术配置文件引用。

先决条件

在自断言技术配置文件的“元数据”部分中，引用的 ContentDefinition 需要DataUri设置为页面协定版本 2.1.9 或更高版本。例如：

<ContentDefinition Id="api.selfasserted">
  <LoadUri>~/tenant/default/selfAsserted.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:selfasserted:2.1.9</DataUri>
  ...

定义显示控件

DisplayControl 元素包含以下属性：

特征	必选	DESCRIPTION
`Id`	是的	用于显示控件的标识符。可以引用它。
`UserInterfaceControlType`	是的	显示控件的类型。目前支持 VerificationControl。

验证控制

验证显示控件验证声明，例如电子邮件地址或电话号码，并向用户发送验证码。下图演示了一个自断言注册页面，其中包含两个用于验证主要和辅助电子邮件地址的显示控件。

显示电子邮件验证显示控件的屏幕截图

DisplayControl 元素包含以下元素：

元素	出现次数	DESCRIPTION
`InputClaims`	0:1	InputClaims 用于预填充要从用户收集的声明的值。有关详细信息，请参阅 InputClaims 元素。
`DisplayClaims`	0:1	DisplayClaims 用于表示要从用户收集的声明。有关详细信息，请参阅 DisplayClaim 元素。
`OutputClaims`	0:1	OutputClaims 用于表示暂时保存此 DisplayControl 的声明。有关详细信息，请参阅 OutputClaims 元素。
`Actions`	0:1	作用于列出验证技术配置文件，以调用前端发生的用户作。

输入声明

在显示控件中，可以使用 InputClaims 元素预填充要从页面上的用户收集的声明值。可以在引用此显示控件的自断言技术配置文件中定义任何 InputClaimsTransformations 。

以下示例预填充要通过已存在的地址进行验证的电子邮件地址。

<DisplayControl Id="emailControl" UserInterfaceControlType="VerificationControl">
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="emailAddress" />
  </InputClaims>
  ...

显示声明

每种显示控件都需要执行一组不同的显示声明、输出声明和作。

与自断言技术配置文件中定义的显示声明类似，显示声明表示要从显示控件内的用户收集的声明。引用的 ClaimType 元素需要为 Azure AD B2C 支持的用户输入类型指定 UserInputType 元素，例如 TextBox 或 DropdownSingleSelect。如果作需要显示声明值，请将 Required 属性设置为 true 强制用户提供该特定显示声明的值。

某些类型的显示控件需要某些显示声明。例如， VerificationCode 是 VerificationControl 类型的显示控件所必需的。使用属性 ControlClaimType 指定为该所需声明指定的 DisplayClaim。例如：

<DisplayClaim ClaimTypeReferenceId="otpCode" ControlClaimType="VerificationCode" Required="true" />

输出声明

显示控件的 输出声明 不会发送到下一个业务流程步骤。它们暂时保存为当前显示控件会话。可以在同一显示控件的不同作之间共享这些临时声明。

若要将输出声明提升到下一个业务流程步骤，请使用实际自断言技术配置文件的 OutputClaims ，该配置文件引用此显示控件。

显示控件作

显示控件的作是在客户端（浏览器）上执行特定作时在 Azure AD B2C 后端中发生的过程。例如，当用户选择页面上的按钮时要执行的验证。

作定义 验证技术配置文件的列表。它们用于验证显示控件的某些或全部显示声明。验证技术配置文件会验证用户输入，并可能会向用户返回错误。可以在显示控件作中使用 ContinueOnError、 ContinueOnSuccess 和 前置条件 ，类似于它们在自断言技术配置文件中的验证技术配置文件中使用的方式。

行动

Actions 元素包含以下元素：

元素	出现次数	DESCRIPTION
`Action`	1：n	要执行的作列表。

行动

Action 元素包含以下属性：

特征	必选	DESCRIPTION
`Id`	是的	操作的类型。可能的值：`SendCode` 或 `VerifyCode`。该值 `SendCode` 向用户发送代码。此作可能包含两个验证技术配置文件：一个用于生成代码，一个用于发送它。该值 `VerifyCode` 验证用户在输入文本框中键入的代码。

Action 元素包含以下元素：

元素	出现次数	DESCRIPTION
`ValidationClaimsExchange`	1:1	用于验证引用技术配置文件的某些或全部显示声明的技术配置文件的标识符。引用的技术配置文件的所有输入声明都必须显示在引用技术配置文件的显示声明中。

ValidationClaimsExchange

ValidationClaimsExchange 元素包含以下元素：

元素	出现次数	DESCRIPTION
`ValidationClaimsExchangeTechnicalProfile`	1：n	用于验证引用技术配置文件的某些或全部显示声明的技术配置文件。

ValidationClaimsExchangeTechnicalProfile 元素包含以下属性：

特征	必选	DESCRIPTION
`TechnicalProfileReferenceId`	是的	策略或父策略中已定义的技术配置文件的标识符。

ValidationClaimsExchangeTechnicalProfile 元素包含以下元素：

元素	出现次数	DESCRIPTION
`Preconditions`	0:1	必须满足验证技术配置文件才能执行的先决条件列表。

Precondition 元素包含以下属性：

特征	必选	DESCRIPTION
`Type`	是的	要针对前置条件执行的检查或查询的类型。可能的值：`ClaimsExist` 或 `ClaimEquals`。 `ClaimsExist` 指定如果用户的当前声明集中存在指定的声明，则应执行这些作。 `ClaimEquals` 指定在指定声明存在且其值等于指定值时应执行的作。
`ExecuteActionsIf`	是的	指示在测试为 true 还是 false 时应执行前置条件中的作。

Precondition 元素包含以下元素：

元素	出现次数	DESCRIPTION
`Value`	1：n	检查使用的数据。如果此检查的类型为 `ClaimsExist`，此字段指定要查询的 ClaimTypeReferenceId。如果检查的类型为 `ClaimEquals`，此字段指定要查询的 ClaimTypeReferenceId。指定要在另一个值元素中签入的值。
`Action`	1:1	如果业务流程步骤中的前置条件检查为 true，则应执行的作。作的值设置为`SkipThisValidationTechnicalProfile`，该值指定不应执行关联的验证技术配置文件。

以下示例使用 Microsoft Entra ID SSPR 技术配置文件发送并验证电子邮件地址。

<DisplayControl Id="emailVerificationControl" UserInterfaceControlType="VerificationControl">
  <InputClaims></InputClaims>
  <DisplayClaims>
    <DisplayClaim ClaimTypeReferenceId="email" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="verificationCode" ControlClaimType="VerificationCode" Required="true" />
  </DisplayClaims>
  <OutputClaims></OutputClaims>
  <Actions>
    <Action Id="SendCode">
      <ValidationClaimsExchange>
        <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AadSspr-SendCode" />
      </ValidationClaimsExchange>
    </Action>
    <Action Id="VerifyCode">
      <ValidationClaimsExchange>
        <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AadSspr-VerifyCode" />
      </ValidationClaimsExchange>
    </Action>
  </Actions>
</DisplayControl>

以下示例根据用户选择具有前置条件的 mfaType 声明，在电子邮件或短信中发送代码。

<Action Id="SendCode">
  <ValidationClaimsExchange>
    <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AzureMfa-SendSms">
      <Preconditions>
        <Precondition Type="ClaimEquals" ExecuteActionsIf="true">
          <Value>mfaType</Value>
          <Value>email</Value>
          <Action>SkipThisValidationTechnicalProfile</Action>
        </Precondition>
      </Preconditions>
    </ValidationClaimsExchangeTechnicalProfile>
    <ValidationClaimsExchangeTechnicalProfile TechnicalProfileReferenceId="AadSspr-SendEmail">
      <Preconditions>
        <Precondition Type="ClaimEquals" ExecuteActionsIf="true">
          <Value>mfaType</Value>
          <Value>phone</Value>
          <Action>SkipThisValidationTechnicalProfile</Action>
        </Precondition>
      </Preconditions>
    </ValidationClaimsExchangeTechnicalProfile>
  </ValidationClaimsExchange>
</Action>

引用显示控件

显示控件在自断言技术配置文件的显示声明中引用。

例如：

<TechnicalProfile Id="SelfAsserted-ProfileUpdate">
  ...
  <DisplayClaims>
    <DisplayClaim DisplayControlReferenceId="emailVerificationControl" />
    <DisplayClaim DisplayControlReferenceId="PhoneVerificationControl" />
    <DisplayClaim ClaimTypeReferenceId="displayName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="givenName" Required="true" />
    <DisplayClaim ClaimTypeReferenceId="surName" Required="true" />

通过