Элементы управления Display

Статья
01/11/2024

Примечание.

В Azure Active Directory B2C пользовательские политики преимущественно предназначены для выполнения сложных сценариев. В большинстве случаев рекомендуется использовать встроенные потоки пользователей. Ознакомьтесь со статьей Начало работы с настраиваемыми политиками в Azure Active Directory B2C, чтобы узнать о базовом пакете настраиваемых политик, если еще не сделали этого.

Элемент управления отображением — это элемент пользовательского интерфейса, который реализует особую функциональность и взаимодействует с внутренней службой Azure Active Directory B2C (Azure AD B2C). Она позволяет пользователю выполнять на странице действия, которые вызывают технический профиль проверки из внутренней службы. Элементы управления отображением размещаются на этой странице, и на них ссылается технический профиль с самостоятельным подтверждением.

Необходимые компоненты

В разделе Metadata (Метаданные) технического профиля с самостоятельным подтверждением есть ссылка на 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 содержит следующие атрибуты:

Атрибут	Обязательное поле	Описание:
`Id`	Да	Идентификатор, который назначен этому элементу управления отображением. На него могут указывать ссылки.
`UserInterfaceControlType`	Да	Тип элемента управления отображением. В настоящее время поддерживается AuthenticationControl, элементы управления TOTP и элементы управления CAPTCHA.

Контроль проверки

Элемент управления отображением позволяет проверить утверждения, например адреса электронной почты или номера телефона, на который пользователю будет отправлен код проверки. На следующем рисунке вы видите страницу регистрации с самостоятельным подтверждением, где размещены два элемента управления отображением, в которых выполняется проверка основного и дополнительного адресов электронной почты.

Screenshot showing email verification display control

Элементы управления TOTP

Элементы управления отображением TOTP — это набор элементов управления отображением, которые предоставляют многофакторную проверку подлинности TOTP с помощью приложения Microsoft Authenticator. На следующем рисунке показана страница регистрации TOTP с тремя элементами управления отображением.

Screenshot showing TOTP display controls

QrCodeControl

Элемент DisplayControl содержит следующие элементы.

Элемент	Вхождения	Description
`InputClaims`	00:14	Элементы InputClaim используются для предварительного заполнения значений утверждений, которые нужно собирать от пользователя. Дополнительные сведения см. в документации по элементу InputClaim.
`DisplayClaims`	00:14	Элементы DisplayClaim представляют утверждения, которые нужно собирать от пользователя. Дополнительные сведения см. в документации по элементу DisplayClaim.
`OutputClaims`	00:14	Элементы OutputClaim представляют утверждения, которые нужно временно сохранять для этого элемента DisplayControl. Дополнительные сведения см. в документации по элементу OutputClaim.
`Actions`	00:14	Элементы Action используются для перечисления технических профилей проверки, которые будут вызываться в ответ на действия пользователя в интерфейсе.

Входящие утверждения

В элементе управления отображением можно с помощью элементов InputClaim предварительно заполнить значения утверждений, которые будут собраны от пользователя на этой странице. Любой элемент InputClaimsTransformation может быть определен в техническом профиле с самостоятельным подтверждением, который ссылается на этот элемент управления отображением.

В следующем примере предварительно заполняется адрес электронной почты, который мы будем проверять.

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

Отображаемые утверждения

Для каждого типа элементов управления отображением требуется собственный набор утверждений отображения, исходящих утверждений и выполняемых действий.

Как и в случае с утверждениями отображения, которые определяются в техническом профиле с самостоятельным подтверждением, эти утверждения отображения представляют утверждения, которые будут собраны от пользователя в элементе управления отображением. Указанный в ссылке элемент ClaimType должен определять элемент UserInputType для входных данных от пользователя, поддерживаемый службой Azure AD B2C, например TextBox или DropdownSingleSelect. Если для действия значение утверждения отображения является обязательным, задайте для атрибута Required (Обязательный) значение true. Это означает, что пользователь обязан указать значение для этого конкретного утверждения отображения.

Для некоторых типов элементов управления отображением требуются определенные утверждения отображения. Например, VerificationCode является обязательным для элемента управления отображением с типом VerificationControl. С помощью атрибута ControlClaimType можно указать, какой элемент DisplayClaim назначен для этого обязательного утверждения. Например:

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

Исходящие утверждения

Исходящие утверждения элемента управления отображением не отправляются на следующий этап оркестрации. Они сохраняются временно, только для текущего сеанса управления отображением. Эти временные утверждения могут использоваться совместно в нескольких действиях одного элемента управления отображением.

Чтобы передать исходящие утверждения на следующий этап оркестрации, используйте элементы OutputClaim технического профиля с самостоятельным подтверждением, который ссылается на этот элемент управления отображением.

Действия элемента управления отображением

Действияэлемента управления отображением представляют собой процедуры, которые выполняются во внутренней службе Azure AD B2C, когда пользователь выполняет определенное действие на стороне клиента (в браузере). Например, это могут быть проверки, выполняемые по нажатию кнопки на странице.

Каждое действие определяет список технических профилей проверки. Они используются для проверки некоторых или всех утверждений отображения элемента управления отображением. Технический профиль проверки проверяет полученные от пользователя входные данные и возвращает ошибку пользователю. В действии элемента управления отображением вы можете использовать ContinueOnError, ContinueOnSuccess и Preconditions по тем же правилам, что и в технических профилях проверки из технического профиля с самостоятельным подтверждением.

Действия

Элемент Actions содержит следующий элемент:

Элемент	Вхождения	Description
`Action`	1:n	Список действий, которые нужно выполнить.

Действие

Элемент Action содержит следующий атрибут:

Атрибут	Обязательное поле	Описание:
`Id`	Да	Тип операции. Возможные значения: `SendCode` или `VerifyCode`. Значение `SendCode` отправляет пользователю код. Это действие может содержать два технических профиля проверки: один — для создания кода, другой — для его отправки. Значение `VerifyCode` проверяет код, введенный пользователем в текстовое поле ввода.

Элемент Action содержит следующий элемент:

Элемент	Вхождения	Description
`ValidationClaimsExchange`	1:1	Идентификаторы технических профилей, которые используются для проверки некоторых или всех утверждений отображения технического профиля, который ссылается на этот элемент. Все входящие утверждения технического профиля, который включается по ссылке, должны присутствовать в списке исходящих утверждений технического профиля, который ссылается на этот элемент.

ValidationClaimsExchange

Элемент ValidationClaimsExchange содержит следующий элемент:

Элемент	Вхождения	Description
`ValidationClaimsExchangeTechnicalProfile`	1:n	Технический профиль используется для проверки некоторых или всех утверждений отображения технического профиля, который ссылается на этот элемент.

Элемент ValidationClaimsExchangeTechnicalProfile содержит следующий атрибут:

Атрибут	Обязательное поле	Описание:
`TechnicalProfileReferenceId`	Да	Идентификатор технического профиля, который уже определен в политике или родительской политике.

Элемент ValidationClaimsExchangeTechnicalProfile содержит следующий элемент:

Элемент	Вхождения	Description
`Preconditions`	00:14	Список предварительных условий, которые необходимо соблюдать для выполнения технического профиля проверки.

Элемент Precondition содержит следующие атрибуты.

Атрибут	Обязательное поле	Описание:
`Type`	Да	Тип выполняемой проверки или запроса для данного предварительного условия. Возможные значения: `ClaimsExist` или `ClaimEquals`. `ClaimsExist` указывает, что действия должны выполняться в том случае, если указанные утверждения существуют в наборе утверждений текущего пользователя. `ClaimEquals` указывает, что действия должны выполняться в том случае, если указанное утверждение существует и его значение равно указанному.
`ExecuteActionsIf`	Да	Указывает, следует ли выполнять действия в предварительном условии, если тест возвращает true или false.

Элементы Precondition содержат следующие элементы:

Элемент	Вхождения	Description
`Value`	1:n	Данные, используемые при проверке. Если тип этой проверки равен `ClaimsExist`, то это поле задает ClaimTypeReferenceId для запроса. Если тип проверки равен `ClaimEquals`, то это поле задает ClaimTypeReferenceId для запроса. Определяет значение, которое нужно найти в другом элементе значения.
`Action`	1:1	Действие, которое требуется выполнить, если в результате проверки предварительного условия в рамках шага оркестрации получено значение true. Параметр Action (Действие) имеет значение `SkipThisValidationTechnicalProfile`, что указывает на то, что соответствующий технический профиль проверки не должен выполняться.

В следующем примере отправляется и проверяется адрес электронной почты с помощью технического профиля SSPR идентификатора Microsoft Entra ID.

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

Следующие шаги

Примеры использования элемента управления отображением см. в следующих статьях: