显示控件

项目
2024/10/14

备注

在 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 元素包含以下属性：

Attribute	必须	说明
`Id`	是	用于显示控件的一个标识符。可以对它进行引用。
`UserInterfaceControlType`	是	显示控件的类型。当前支持的是 VerificationControl。

验证控制

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

Screenshot showing email verification display control

DisplayControl 元素包含以下元素：

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

输入声明

在显示控件中，可以使用 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 和 Preconditions，使用方式类似于在自断言技术配置文件中的验证技术配置文件中使用它们的方式。

操作

Actions 元素包含以下元素：

元素	出现次数	说明
`Action`	1:n	要执行的操作的列表。

操作

Action 元素包含以下属性：

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

Action 元素包含以下元素：

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

ValidationClaimsExchange

ValidationClaimsExchange 元素包含以下元素：

元素	出现次数	说明
`ValidationClaimsExchangeTechnicalProfile`	1:n	要用于验证引用技术配置文件的部分或所有显示声明的技术配置文件。

ValidationClaimsExchangeTechnicalProfile 元素包含以下属性：

属性	必须	说明
`TechnicalProfileReferenceId`	是	已在策略或父策略中定义的技术配置文件的标识符。

ValidationClaimsExchangeTechnicalProfile 元素包含以下元素：

元素	出现次数	说明
`Preconditions`	0:1	为执行验证技术配置文件而必须满足执行的前置条件的列表。

Precondition 元素包含以下属性：

属性	必须	说明
`Type`	是	要对前置条件执行的检查或查询的类型。可能的值：`ClaimsExist` 或 `ClaimEquals`。如果指定的声明存在于用户的当前声明集中，则 `ClaimsExist` 指定应执行的操作。如果指定的声明存在并且其值等于指定的值，则 `ClaimEquals` 指定应执行的操作。
`ExecuteActionsIf`	是	指示在测试为 true 或 false 时是否应执行前置条件中的操作。

Precondition 元素包含以下元素：

元素	出现次数	说明
`Value`	1:n	检查使用的数据。如果此检查的类型是 `ClaimsExist`，则此字段指定要进行查询的 ClaimTypeReferenceId。如果检查的类型是 `ClaimEquals`，则此字段指定要进行查询的 ClaimTypeReferenceId。指定要在另一个值元素中检查的值。
`Action`	1:1	在业务流程步骤中的前置条件检查为 true 时应执行的操作。 Action 的值设置为 `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" />

通过