顯示控制項

注意

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

屬性	必要	描述:
Id	Yes	用於顯示控件的識別碼。 可以 參考它。
UserInterfaceControlType	Yes	顯示控制件的類型。 目前支援 的是 VerificationControl、 TOTP 控件和 CAPTCHA 控制件。

驗證控制

驗證 顯示控制項 會驗證宣告，例如電子郵件地址或電話號碼，並傳送驗證碼給使用者。 下圖說明自我判斷提示註冊頁面，其中包含兩個驗證主要和次要電子郵件地址的顯示控件。

TOTP 控制件

TOTP 顯示控件是一組顯示控件，可透過 Microsoft Authenticator 應用程式提供 TOTP 多重要素驗證。 下圖說明具有三個顯示控件的 TOTP 註冊頁面。

QrCodeControl

DisplayControl 元素包含下列元素：

Element	發生次數	描述
InputClaims	0:1	InputClaims 可用來預先填入要從使用者收集之宣告的值。 如需詳細資訊，請參閱 InputClaims 元素。
DisplayClaims	0:1	DisplayClaims 用來代表要從使用者收集的宣告。 如需詳細資訊，請參閱 DisplayClaim 元素。
OutputClaims	0:1	OutputClaims 用來代表暫時儲存此 DisplayControl 的宣告。 如需詳細資訊，請參閱 OutputClaims 元素。
Actions	0:1	動作 可用來列出驗證技術配置檔，以叫用前端發生的用戶動作。

輸入宣告

在顯示控件中，您可以使用 InputClaims 元素預先填入要從頁面上使用者收集的宣告值。 任何 InputClaimsTransformations 都可以在自我判斷技術配置檔中定義，此配置檔會參考此顯示控件。

下列範例會預先填入電子郵件位址，以已存在的地址進行驗證。

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

顯示宣告

每種顯示控件類型都需要執行一組不同的顯示宣告、 輸出宣告和 動作 。

類似於自我判斷技術配置檔中定義的顯示宣告，顯示宣告代表要從顯示控件內的使用者收集的宣告。 參考的 ClaimType 元素必須指定 Azure AD B2C 所支援之使用者輸入類型的 UserInputType 元素，例如 TextBox 或 DropdownSingleSelect。 如果 Action 需要顯示宣告值，請將 Required 屬性設定為 true ，以強制使用者提供該特定顯示宣告的值。

特定類型的顯示控制項需要特定的顯示宣告。 例如，VerificationControl 類型的顯示控件需要 VerificationCode。 使用 ControlClaimType 屬性來指定該必要宣告所指定的 DisplayClaim。 例如：

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

輸出宣告

顯示控件的輸出宣告不會傳送至下一個協調流程步驟。 它們只會暫時儲存給目前的顯示控件會話。 這些暫存宣告可以在相同顯示控件的不同動作之間共用。

若要將輸出宣告反升至下一個協調流程步驟，請使用 實際自我判斷技術配置檔的 OutputClaims ，其會參考此顯示控件。

顯示控制項動作

顯示 控制元件的動作 是當使用者在用戶端 （瀏覽器） 上執行特定動作時，在 Azure AD B2C 後端中發生的程式。 例如，當用戶選取頁面上的按鈕時，要執行的驗證。

動作會定義驗證技術配置檔的清單。 它們用於驗證顯示控制件的一些或所有顯示宣告。 驗證技術配置檔會驗證使用者輸入，並可能會將錯誤傳回給使用者。 您可以在顯示控制項動作中使用 ContinueOnError、ContinueOnSuccess 和前置條件，類似於它們在自我判斷技術設定檔中驗證技術設定檔中使用的方式。

動作

Actions 元素包含下列元素：

Element	發生次數	描述
Action	1：n	要執行的動作清單。

動作

Action 元素包含下列屬性：

屬性	必要	描述:
Id	Yes	作業的類型。 可能的值： SendCode 或 VerifyCode。 值 SendCode 會將程式代碼傳送給使用者。 此動作可能包含兩個驗證技術配置檔：一個用來產生程序代碼，另一個用來傳送程序代碼。 值 VerifyCode 會驗證使用者在輸入文字框中輸入的程序代碼。

Action 元素包含下列元素：

Element	發生次數	描述
ValidationClaimsExchange	1:1	用來驗證參考技術配置檔之部分或所有顯示宣告的技術配置文件標識碼。 參考技術配置檔的所有輸入宣告都必須出現在參考技術配置文件的顯示宣告中。

ValidationClaimsExchange

ValidationClaimsExchange 元素包含下列元素：

Element	發生次數	描述
ValidationClaimsExchangeTechnicalProfile	1：n	用來驗證參考技術配置檔之部分或所有顯示宣告的技術配置檔。

ValidationClaimsExchangeTechnicalProfile 元素包含下列屬性：

屬性	必要	描述:
TechnicalProfileReferenceId	Yes	已在原則或父原則中定義之技術配置檔的標識碼。

ValidationClaimsExchangeTechnicalProfile 元素包含下列元素：

Element	發生次數	描述
Preconditions	0:1	必須滿足驗證技術配置檔才能執行的先決條件清單。

Precondition 元素包含下列屬性：

屬性	必要	描述:
Type	Yes	要針對前置條件執行的檢查或查詢類型。 可能的值： ClaimsExist 或 ClaimEquals。 ClaimsExist 指定如果指定的宣告存在於使用者目前的宣告集中，則應該執行動作。 ClaimEquals 指定如果指定的宣告存在且其值等於指定的值，則應該執行動作。
ExecuteActionsIf	Yes	指出測試為 true 或 false 時，是否應該執行前置條件中的動作。

前置條件元素包含下列元素：

Element	發生次數	描述
Value	1：n	檢查所使用的數據。 如果此檢查的類型為 ClaimsExist，此字段會指定要查詢的 ClaimTypeReferenceId。 如果檢查的類型為 ClaimEquals，此字段會指定要查詢的 ClaimTypeReferenceId。 指定要簽入另一個 value 元素中的值。
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 宣告，以電子郵件或 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" />

下一步

如需使用顯示控件的範例，請參閱：

• 使用Mailjet進行自訂電子郵件驗證
• 使用 SendGrid 進行自訂電子郵件驗證