显示控件Display controls

备注

在 Azure Active Directory B2C 中,custom policies 主要用于解决复杂方案。In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. 大多数情况下,建议使用内置的用户流For most scenarios, we recommend that you use built-in user flows.

显示控件 是一个具有特殊功能的用户界面元素,可以与 Azure Active Directory B2C (Azure AD B2C) 后端服务进行交互。A display control is a user interface element that has special functionality and interacts with the Azure Active Directory B2C (Azure AD B2C) back-end service. 它允许用户在页面上执行某些操作,这些操作在后端调用验证技术配置文件It allows the user to perform actions on the page that invoke a validation technical profile at the back end. 显示控件显示在页面上,由自断言技术配置文件引用。Display controls are displayed on the page and are referenced by a self-asserted technical profile.

下图展示了一个自断言注册页面,其中包含两个用于验证主要电子邮件地址和辅助电子邮件地址的显示控件。The following image illustrates a self-asserted sign-up page with two display controls that validate a primary and secondary email address.

呈现了显示控件的示例

备注

此功能目前以公共预览版提供。This feature is in public preview.

必备条件Prerequisites

自断言技术配置文件元数据部分中,引用的 ContentDefinition 需要将 DataUri 设置为页面协定版本2.0.0 或更高版本。In the Metadata section of a self-asserted technical profile, the referenced ContentDefinition needs to have DataUri set to page contract version 2.0.0 or higher. 例如:For example:

<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.0.0</DataUri>
  ...

定义显示控件Defining display controls

DisplayControl 元素包含以下属性:The DisplayControl element contains the following attributes:

AttributeAttribute 必选Required 说明Description
IDId Yes 用于显示控件的一个标识符。An identifier that's used for the display control. 可以对它进行引用It can be referenced.
UserInterfaceControlTypeUserInterfaceControlType Yes 显示控件的类型。The type of the display control. 当前支持的是 VerificationControlCurrently supported is VerificationControl

DisplayControl 元素包含以下元素:The DisplayControl element contains the following elements:

元素Element 出现次数Occurrences 说明Description
InputClaimsInputClaims 0:10:1 InputClaims 用于预填充要从用户那里收集的声明的值。InputClaims are used to prepopulate the value of the claims to be collected from the user. 有关详细信息,请参阅 InputClaims 元素。For more information, see InputClaims element.
DisplayClaimsDisplayClaims 0:10:1 DisplayClaims 用于表示要从用户那里收集的声明。DisplayClaims are used to represent claims to be collected from the user. 有关详细信息,请参阅 DisplayClaim 元素。For more information, see DisplayClaim element.
OutputClaimsOutputClaims 0:10:1 OutputClaims 用于表示要暂时为此 DisplayControl 保存的声明。OutputClaims are used to represent claims to be saved temporarily for this DisplayControl . 有关详细信息,请参阅 OutputClaims 元素。For more information, see OutputClaims element.
操作Actions 0:10:1 Actions 用于列出要针对在前端发生的用户操作调用的验证技术配置文件。Actions are used to list the validation technical profiles to invoke for user actions happening at the front-end.

输入声明Input claims

在显示控件中,可以使用 InputClaims 元素预填充要在页面上从用户那里收集的声明的值。In a display control, you can use InputClaims elements to prepopulate the value of claims to collect from the user on the page. 可在引用此显示控件的自断言技术配置文件中定义任何 InputClaimsTransformationsAny InputClaimsTransformations can be defined in the self-asserted technical profile which references this display control.

以下示例使用已存在的地址预填充要验证的电子邮件地址。The following example prepopulates the email address to be verified with the address already present.

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

显示声明Display claims

每种类型的显示控件都需要一组不同的显示声明、输出声明,以及要执行的操作Each type of display control requires a different set of display claims, output claims, and actions to be performed.

与在 自断言技术配置文件中定义的 显示声明 类似,显示声明表示在显示控件中要从用户那里收集的声明。Similar to the display claims defined in a self-asserted technical profile, the display claims represent the claims to be collected from the user within the display control. 引用的 ClaimType 元素需要指定 Azure AD B2C 支持的某个用户输入类型的 UserInputType 元素,例如 TextBoxDropdownSingleSelectThe ClaimType element referenced needs to specify the UserInputType element for a user input type supported by Azure AD B2C, such as TextBox or DropdownSingleSelect. 如果显示声明值是某个 操作 所必需的,请将 Required 属性设置为 true 来强制用户为该特定的显示声明提供一个值。If a display claim value is required by an Action , set the Required attribute to true to force the user to provide a value for that specific display claim.

某些显示声明是某些类型的显示控件所必需的。Certain display claims are required for certain types of display control. 例如, VerificationCodeVerificationControl 类型的显示控件所必需的。For example, VerificationCode is required for the display control of type VerificationControl . 请使用 ControlClaimType 属性指定为该必需声明指定了哪个 DisplayClaim。Use the attribute ControlClaimType to specify which DisplayClaim is designated for that required claim. 例如: 。For example:

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

输出声明Output claims

显示控件的 输出声明 不会发送到下一个业务流程步骤。The output claims of a display control are not sent to the next orchestration step. 它们仅暂时保存以用于当前显示控件会话。They are saved temporarily only for the current display control session. 这些暂时声明可在同一显示控件的不同操作之间共享。These temporary claims can be shared between the different actions of the same display control.

若要将输出声明传播到下一个业务流程步骤,请使用引用此显示控件的实际自断言技术配置文件的 OutputClaimsTo bubble up the output claims to the next orchestration step, use the OutputClaims of the actual self-asserted technical profile which references this display control.

显示控件操作Display control Actions

显示控件的 操作 是用户在客户端(浏览器)执行特定操作时在 Azure AD B2C 后端发生的过程。The Actions of a display control are procedures that occur in the Azure AD B2C back end when a user performs a certain action on the client side (the browser). 例如,当用户选择页面上的某个按钮时要执行的验证。For example, the validations to perform when the user selects a button on the page.

操作定义 验证技术配置文件 的列表。An action defines a list of validation technical profiles . 它们用于验证显示控件的部分或全部显示声明。They are used for validating some or all of the display claims of the display control. 验证技术配置文件将验证用户输入,并可能向用户返回错误。The validation technical profile validates the user input and may return an error to the user. 可以在显示控件操作中使用 ContinueOnErrorContinueOnSuccessPreconditions ,使用方式类似于在自断言技术配置文件中的 验证技术配置文件中使用它们的方式。You can use ContinueOnError , ContinueOnSuccess , and Preconditions in the display control Action similar to the way they're used in validation technical profiles in a self asserted technical profile.

操作Actions

Actions 元素包含以下元素:The Actions element contains the following element:

元素Element 出现次数Occurrences 说明Description
操作Action 1:n1:n 要执行的操作的列表。List of actions to be executed.

操作Action

Action 元素包含以下属性:The Action element contains the following attribute:

属性Attribute 必须Required 说明Description
IDId Yes 操作的类型。The type of operation. 可能的值:SendCodeVerifyCodePossible values: SendCode or VerifyCode. SendCode 值向用户发送代码。The SendCode value sends a code to the user. 此操作可能包含两个验证技术配置文件:一个用于生成代码,另一个用于发送代码。This action may contain two validation technical profiles: one to generate a code and one to send it. VerifyCode 值验证用户在输入文本框中键入的代码。The VerifyCode value verifies the code the user typed in the input textbox.

Action 元素包含以下元素:The Action element contains the following element:

元素Element 出现次数Occurrences 说明Description
ValidationClaimsExchangeValidationClaimsExchange 1:11:1 用于验证引用技术配置文件的部分或所有显示声明的技术配置文件的标识符。The identifiers of technical profiles that are used to validate some or all of the display claims of the referencing technical profile. 被引用技术配置文件的所有输入声明必须出现在引用技术配置文件的显示声明中。All input claims of the referenced technical profile must appear in the display claims of the referencing technical profile.

ValidationClaimsExchangeValidationClaimsExchange

ValidationClaimsExchange 元素包含以下元素:The ValidationClaimsExchange element contains the following element:

元素Element 出现次数Occurrences 说明Description
ValidationTechnicalProfileValidationTechnicalProfile 1:n1:n 要用于验证引用技术配置文件的部分或所有显示声明的技术配置文件。A technical profile to be used for validating some or all of the display claims of the referencing technical profile.

ValidationTechnicalProfile 元素包含以下属性:The ValidationTechnicalProfile element contains the following attributes:

属性Attribute 必须Required 说明Description
ReferenceIdReferenceId Yes 已在策略或父策略中定义的技术配置文件的标识符。An identifier of a technical profile already defined in the policy or parent policy.
ContinueOnErrorContinueOnError No 指示在此验证技术配置文件引发错误时,任何后续验证技术配置文件是否应继续进行验证。Indicates whether validation of any subsequent validation technical profiles should continue if this validation technical profile raises an error. 可能的值:truefalse(默认值,进一步验证配置文件的处理会停止,并且返回错误)。Possible values: true or false (default, processing of further validation profiles will stop and an error will be returned).
ContinueOnSuccessContinueOnSuccess No 指示在此验证技术配置文件成功时,任何后续验证配置文件是否应继续进行验证。Indicates whether validation of any subsequent validation profiles should continue if this validation technical profile succeeds. 可能的值:truefalsePossible values: true or false. 默认值是 true,表示进一步验证配置文件的处理会继续进行。The default is true, meaning that the processing of further validation profiles will continue.

ValidationTechnicalProfile 元素包含以下元素:The ValidationTechnicalProfile element contains the following element:

元素Element 出现次数Occurrences 说明Description
PreconditionsPreconditions 0:10:1 为执行验证技术配置文件而必须满足执行的前置条件的列表。A list of preconditions that must be satisfied for the validation technical profile to execute.

Precondition 元素包含以下属性:The Precondition element contains the following attributes:

属性Attribute 必须Required 说明Description
Type Yes 要对前置条件执行的检查或查询的类型。The type of check or query to perform for the precondition. 可能的值:ClaimsExistClaimEqualsPossible values: ClaimsExist or ClaimEquals. 如果指定的声明存在于用户的当前声明集中,则 ClaimsExist 指定应执行的操作。ClaimsExist specifies that the actions should be performed if the specified claims exist in the user's current claim set. 如果指定的声明存在并且其值等于指定的值,则 ClaimEquals 指定应执行的操作。ClaimEquals specifies that the actions should be performed if the specified claim exists and its value is equal to the specified value.
ExecuteActionsIf Yes 指示在测试为 true 或 false 时是否应执行前置条件中的操作。Indicates whether the actions in the precondition should be performed if the test is true or false.

Precondition 元素包含以下元素:The Precondition element contains following elements:

元素Element 出现次数Occurrences 说明Description
ValueValue 1:n1:n 检查使用的数据。The data that is used by the check. 如果此检查的类型是 ClaimsExist,则此字段指定要进行查询的 ClaimTypeReferenceId。If the type of this check is ClaimsExist, this field specifies a ClaimTypeReferenceId to query for. 如果检查的类型是 ClaimEquals,则此字段指定要进行查询的 ClaimTypeReferenceId。If the type of check is ClaimEquals, this field specifies a ClaimTypeReferenceId to query for. 指定要在另一个值元素中检查的值。Specify the value to be checked in another value element.
操作Action 1:11:1 在业务流程步骤中的前置条件检查为 true 时应执行的操作。The action that should be taken if the precondition check within an orchestration step is true. Action 的值设置为 SkipThisValidationTechnicalProfile,它指定不应执行关联的验证技术配置文件。The value of the Action is set to SkipThisValidationTechnicalProfile, which specifies that the associated validation technical profile should not be executed.

以下示例使用 Azure AD SSPR 技术配置文件发送和验证电子邮件地址。The following example sends and verifies the email address using Azure AD SSPR technical profile.

<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 声明通过电子邮件或短信来发送代码。The following example sends a code either in email or SMS based on the user's selection of the mfaType claim with preconditions.

<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>

引用显示控件Referencing display controls

显示控件在自断言技术配置文件显示声明中引用。Display controls are referenced in the display claims of the self-asserted technical profile.

例如:For example:

<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" />