Display controls

Article
10/14/2024

Note

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. If you've not done so, learn about custom policy starter pack in Get started with custom policies in Active Directory 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.

Prerequisites

In the Metadata section of a self-asserted technical profile, the referenced ContentDefinition needs to have DataUri set to page contract version 2.1.9 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.1.9</DataUri>
  ...

Defining display controls

The DisplayControl element contains the following attributes:

Attribute	Required	Description
`Id`	Yes	An identifier that's used for the display control. It can be referenced.
`UserInterfaceControlType`	Yes	The type of the display control. Currently supported is VerificationControl.

Verification control

The verification display control verifies claims, for example an email address or phone number, with a verification code sent to the user. The following image illustrates a self-asserted sign-up page with two display controls that validate a primary and secondary email address.

Screenshot showing email verification display control

The DisplayControl element contains the following elements:

Element	Occurrences	Description
`InputClaims`	0:1	InputClaims are used to prepopulate the value of the claims to be collected from the user. For more information, see InputClaims element.
`DisplayClaims`	0:1	DisplayClaims are used to represent claims to be collected from the user. For more information, see DisplayClaim element.
`OutputClaims`	0:1	OutputClaims are used to represent claims to be saved temporarily for this DisplayControl. For more information, see OutputClaims element.
`Actions`	0:1	Actions are used to list the validation technical profiles to invoke for user actions happening at the front end.

Input claims

In a display control, you can use InputClaims elements to prepopulate the value of claims to collect from the user on the page. Any 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. The ClaimType element referenced needs to specify the UserInputType element for a user input type supported by Azure AD B2C, such as TextBox or DropdownSingleSelect. 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. For example, VerificationCode is required for the display control of type VerificationControl. 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.

To 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

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

The Actions element contains the following element:

Element	Occurrences	Description
`Action`	1:n	List of actions to be executed.

Action

The Action element contains the following attribute:

Attribute	Required	Description
`Id`	Yes	The type of operation. Possible values: `SendCode` or `VerifyCode`. 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. The `VerifyCode` value verifies the code the user typed in the input textbox.

The Action element contains the following element:

Element	Occurrences	Description
`ValidationClaimsExchange`	1: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.

ValidationClaimsExchange

The ValidationClaimsExchange element contains the following element:

Element	Occurrences	Description
`ValidationClaimsExchangeTechnicalProfile`	1:n	A technical profile to be used for validating some or all of the display claims of the referencing technical profile.

The ValidationClaimsExchangeTechnicalProfile element contains the following attribute:

Attribute	Required	Description
`TechnicalProfileReferenceId`	Yes	An identifier of a technical profile already defined in the policy or parent policy.

The ValidationClaimsExchangeTechnicalProfile element contains the following element:

Element	Occurrences	Description
`Preconditions`	0:1	A list of preconditions that must be satisfied for the validation technical profile to execute.

The Precondition element contains the following attributes:

Attribute	Required	Description
`Type`	Yes	The type of check or query to perform for the precondition. Possible values: `ClaimsExist` or `ClaimEquals`. `ClaimsExist` specifies that the actions should be performed if the specified claims exist in the user's current claim set. `ClaimEquals` specifies that the actions should be performed if the specified claim exists and its value is equal to the specified value.
`ExecuteActionsIf`	Yes	Indicates whether the actions in the precondition should be performed if the test is true or false.

The Precondition element contains following elements:

Element	Occurrences	Description
`Value`	1:n	The data that is used by the check. If the type of this check is `ClaimsExist`, this field specifies a ClaimTypeReferenceId to query for. 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:1	The action that should be taken if the precondition check within an orchestration step is true. The value of the Action is set to `SkipThisValidationTechnicalProfile`, which specifies that the associated validation technical profile should not be executed.

The following example sends and verifies the email address using Microsoft Entra ID 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>

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