表示コントロール

注意

Azure Active Directory B2C で、カスタム ポリシーは、主に、複雑なシナリオに取り組む用途向けに設計されています。 ほとんどのシナリオで、組み込みユーザー フローを使用することをお勧めします。 まだ行っていない場合は、Active Directory B2C でのカスタム ポリシーの概要に関する記事で、カスタム ポリシー スターター パックの詳細を確認してください。

表示コントロールは、特別な機能を備え、Azure Active Directory B2C (Azure AD B2C) バックエンド サービスと作用するユーザー インターフェイス要素です。 これにより、ユーザーがバックエンドで検証技術プロファイルを呼び出すページで操作を実行できるようになります。 ページに表示コントロールが表示され、セルフアサート技術プロファイルによって参照されます。

前提条件

セルフアサート技術プロファイルMetadata セクションで参照された ContentDefinitionDataUri をページ コントラクトのバージョン 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 はい 表示コントロールの種類。 現在サポートされているのは VerificationControlTOTP コントロールです。

検証コントロール

検証表示コントロールでは、要求 (電子メール アドレスや電話番号など) をユーザーに送信された確認コードを使用して検証します。 次の図は、プライマリとセカンダリの電子メール アドレスを検証する 2 つの表示コントロールを含むセルフアサート サインアップ ページを示しています。

Screenshot showing email verification display control

TOTP コントロール

TOTP 表示コントロールは、Microsoft Authenticator アプリを使用した TOTP 多要素認証を提供する一連の表示コントロールです。 次の図には、3 つの表示コントロールを含む TOTP 登録ページが示されています。

Screenshot showing TOTP display controls

QrCodeControl

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 要素では、UserInputType 要素として、TextBox または DropdownSingleSelect など Azure AD B2C がサポートするユーザー入力タイプを指定する必要があります。 Action にクレーム表示の値が必要な場合は、Required 属性を true に設定して、ユーザーが特定のクレーム表示の値を指定しなければならないようにします。

特定の種類の表示コントロールには、特定のクレーム表示が必要です。 たとえば、種類が VerificationControl の表示コントロールには、VerificationCode が必要です。 属性 ControlClaimType を使用して、その必須のクレームに対して指定される DisplayClaim を指定します。 次に例を示します。

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

出力クレーム

表示コントロールのクレーム出力は、次のオーケストレーション ステップには送信されません。 これらは、現在の表示コントロール セッションに対してのみ一時的に保存されます。 これらの一時的なクレームは、同じ表示コントロールの異なるアクション間で共有できます。

クレーム出力を次のオーケストレーション ステップにバブルアップするには、この表示コントロールを参照する実際のセルフアサート技術プロファイルの OutputClaims を使用します。

表示コントロールのアクション

表示コントロールのアクションは、ユーザーがクライアント側 (ブラウザー) で特定のアクションを実行したときに Azure AD B2C バックエンドで発生するプロシージャです。 たとえば、ユーザーがページのボタンを選択したときに実行する検証です。

アクションは、検証技術プロファイルの一覧を定義します。 これらは、表示コントロールのクレーム表示の一部またはすべてを検証するために使用されます。 検証技術プロファイルは、ユーザー入力を検証し、ユーザーにエラーを返す場合があります。 セルフアサート技術プロファイルで検証技術プロファイルに使用される方法と同様に、ContinueOnErrorContinueOnSuccess、および Preconditions 表示コントロールのアクションで使用することができます。

アクション

Actions 要素には、次の要素が含まれています。

要素 発生回数 説明
Action 1:n 実行されるアクションの一覧。

アクション

Action 要素には、次の属性が含まれています。

属性 必須 説明
Id はい 操作の種類。 指定できる値: SendCode または VerifyCodeSendCode 値を指定すると、ユーザーにコードが送信されます。 このアクションには、2 つの検証技術プロファイルが含まれている場合があります。1 つはコードを生成するためのもので、もう 1 つはそれを送信するためのものです。 VerifyCode 値を指定すると、ユーザーが入力テキストボックスに入力したコードが検証されます。

Action 要素には、次の要素が含まれています。

要素 発生回数 説明
ValidationClaimsExchange 1:1 参照元の技術プロファイルの要求表示の一部またはすべてを検証するために使用される技術プロファイルの識別子。 参照先の技術プロファイルのすべての要求入力は、参照元の技術プロファイルの要求表示に含まれている必要があります。

ValidationClaimsExchange

ValidationClaimsExchange 要素には、次の要素が含まれています。

要素 発生回数 説明
ValidationClaimsExchangeTechnicalProfile 1:n 参照元の技術プロファイルの要求表示の一部またはすべてを検証するために使用する技術プロファイル。

ValidationClaimsExchangeTechnicalProfile 要素には、次の属性が含まれています。

属性 必須 説明
TechnicalProfileReferenceId はい ポリシーまたは親ポリシーで既に定義されている技術プロファイルの識別子。

ValidationClaimsExchangeTechnicalProfile 要素には、次の要素が含まれています。

要素 発生回数 説明
Preconditions 0:1 検証技術プロファイルを実行するために満たす必要がある前提条件の一覧。

Precondition 要素には、次の属性が含まれています。

属性 必須 説明
Type はい 前提条件に対して実行するチェックまたはクエリの種類。 指定できる値: ClaimsExist または ClaimEqualsClaimsExist を指定すると、指定した要求がユーザーの現在の要求セットに存在する場合に、アクションを実行することが指定されます。 ClaimEquals を指定すると、指定した要求が存在し、その値が指定した値と等しい場合に、アクションを実行することが指定されます。
ExecuteActionsIf はい テストが true または false の場合に前提条件のアクションを実行するかどうかを示します。

Precondition 要素には、次の要素が含まれています。

要素 発生回数 説明
Value 1:n チェックで使用されるデータ。 このチェックの種類が ClaimsExist の場合、このフィールドではクエリ対象の ClaimTypeReferenceId が指定されます。 チェックの種類が ClaimEquals の場合、このフィールドではクエリ対象の ClaimTypeReferenceId が指定されます。 別の値要素でチェックされる値を指定します。
Action 1:1 オーケストレーション手順内の前提条件チェックが true の場合に実行する必要があるアクション。 Action の値が SkipThisValidationTechnicalProfile に設定されます。これは、関連付けられている検証技術プロファイルを実行しないことを指定します。

次の例では、Azure AD 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 要求に基づいてメールまたは SMS でコードを送信します。

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

次のステップ

表示コントロールの使用例については、次を参照してください。