Kontrol tampilan

Artikel
01/11/2024

Catatan

Di Azure Active Directory B2C, kebijakan kustom didesain khusus untuk menangani skenario kompleks. Untuk skenario umum, sebaiknya gunakan alur pengguna bawaan. Jika Anda belum melakukannya, pelajari tentang paket starter kebijakan kustom di Mulai dengan kebijakan kustom di Azure Active Directory B2C.

Kontrol tampilan adalah elemen antarmuka pengguna yang memiliki fungsionalitas khusus dan berinteraksi dengan layanan backend Azure Active Directory B2C (Azure AD B2C). Ini memungkinkan pengguna untuk melakukan tindakan di halaman yang memanggil profil teknis validasi di backend. Kontrol tampilan ditampilkan di halaman dan direferensikan oleh profil teknis yang dinyatakan sendiri.

Prasyarat

Di bagian Metadata dari profil teknis yang ditegaskan sendiri, ContentDefinition yang dirujuk harus DataUri diatur ke kontrak halaman versi 2.1.9 atau yang lebih tinggi. Misalnya:

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

Menentukan kontrol tampilan

Elemen DisplayControl berisi atribut berikut:

Atribut	Wajib	Deskripsi
`Id`	Ya	Pengidentifikasi yang digunakan untuk kontrol tampilan. Ia dapat direferensikan.
`UserInterfaceControlType`	Ya	Jenis kontrol tampilan. Saat ini yang didukung adalah kontrol VerificationControl, TOTP, dan CAPTCHA.

Kontrol verifikasi

Kontrol tampilan verifikasi memverifikasi klaim, misalnya alamat email atau nomor telepon, dengan kode verifikasi yang dikirimkan ke pengguna. Gambar berikut ini mengilustrasikan halaman pendaftaran yang dinyatakan sendiri dengan dua kontrol tampilan yang memvalidasi alamat email utama dan sekunder.

Screenshot showing email verification display control

Kontrol TOTP

Kontrol tampilan TOTP adalah kumpulan kontrol tampilan yang menyediakan autentikasi multifaktor TOTP dengan aplikasi Microsoft Authenticator. Gambar berikut mengilustrasikan halaman pendaftaran TOTP dengan tiga kontrol tampilan.

Screenshot showing TOTP display controls

Kontrol Kode QR

Elemen DisplayControl berisi elemen berikut:

Elemen	Kemunculan	Deskripsi
`InputClaims`	0:1	InputClaims digunakan untuk mengisi nilai klaim yang akan dikumpulkan dari pengguna. Untuk informasi selengkapnya, lihat elemen InputClaims.
`DisplayClaims`	0:1	DisplayClaims digunakan untuk mewakili klaim yang dikumpulkan dari pengguna. Untuk informasi selengkapnya, lihat elemen DisplayClaim.
`OutputClaims`	0:1	OutputClaims digunakan untuk mewakili klaim yang disimpan sementara untuk DisplayControl ini. Untuk informasi selengkapnya, lihat elemen InputClaims.
`Actions`	0:1	Tindakan digunakan untuk membuat daftar profil teknis validasi untuk meminta tindakan pengguna yang terjadi di front end.

Klaim input

Dalam kontrol tampilan, Anda dapat menggunakan elemen InputClaims untuk mengisi nilai klaim untuk dikumpulkan dari pengguna di halaman. Setiap InputClaimsTransformations dapat ditentukan dalam profil teknis yang ditegaskan sendiri, yang merujuk pada kontrol tampilan ini.

Contoh berikut ini mengisi alamat email untuk diverifikasi dengan alamat yang sudah ada.

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

Klaim tampilan

Setiap jenis kontrol tampilan memerlukan serangkaian klaim tampilan, klaim output, dan tindakan yang akan dilakukan.

Mirip dengan klaim tampilan yang didefinisikan dalam profil teknis yang dinyatakan sendiri, klaim tampilan mewakili klaim yang dikumpulkan dari pengguna dalam kontrol tampilan. Elemen ClaimType yang direferensikan harus menentukan elemen UserInputType untuk jenis input pengguna yang didukung oleh Azure AD B2C, seperti TextBox atau DropdownSingleSelect. Jika nilai klaim tampilan diharuskan oleh Tindakan, tetapkan atribut Wajib ke true untuk memaksa pengguna memberikan nilai untuk klaim tampilan tertentu tersebut.

Klaim tampilan tertentu diharuskan untuk jenis kontrol tampilan tertentu. Misalnya, VerificationCode diharuskan untuk kontrol tampilan jenis VerificationControl. Gunakan atribut ControlClaimType untuk menentukan DisplayClaim mana yang ditunjuk untuk klaim yang diharuskan. Misalnya:

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

Klaim output

Klaim output kontrol tampilan tidak dikirim ke langkah orkestrasi berikutnya. Klaim tersebut disimpan sementara hanya untuk sesi kontrol tampilan saat ini. Klaim sementara ini dapat dibagikan di antara berbagai tindakan kontrol tampilan yang sama.

Untuk meningkatkan klaim output ke langkah orkestrasi berikutnya, gunakan Klaim Keluaran dari profil teknis nyata yang ditegaskan sendiri, yang merujuk pada kontrol tampilan ini.

Tindakan Kontrol Tampilan

Tindakan kontrol tampilan adalah prosedur yang terjadi di backend Azure AD B2C saat pengguna melakukan tindakan tertentu di sisi klien (browser). Misalnya, validasi yang akan dilakukan saat pengguna memilih tombol di halaman.

Tindakan mendefinisikan daftar profil teknis validasi. Mereka digunakan untuk memvalidasi beberapa atau semua klaim tampilan dari kontrol tampilan. Profil teknis validasi memvalidasi input pengguna dan dapat menampilkan kesalahan kepada pengguna. Anda dapat menggunakan ContinueOnError, ContinueOnSuccess, dan Prasyarat dalam Tindakan kontrol tampilan yang serupa dengan cara mereka digunakan di profil teknis validasi dalam profil teknis yang menegaskan diri.

Tindakan

Elemen Tindakan berisi elemen berikut:

Elemen	Kemunculan	Deskripsi
`Action`	1:n	Daftar tindakan yang akan dijalankan.

Perbuatan

Elemen Tindakan berisi atribut berikut:

Atribut	Wajib	Deskripsi
`Id`	Ya	Jenis operasi. Nilai yang mungkin: `SendCode` atau `VerifyCode`. Nilai `SendCode` mengirim kode ke pengguna. Tindakan ini mungkin berisi dua profil teknis validasi: satu untuk menghasilkan kode dan satu untuk mengirimnya. Nilai `VerifyCode` memverifikasi kode yang diketik pengguna di kotak teks input.

Elemen Tindakan berisi elemen berikut:

Elemen	Kemunculan	Deskripsi
`ValidationClaimsExchange`	1:1	Pengidentifikasi profil teknis yang digunakan untuk memvalidasi beberapa atau semua klaim tampilan dari profil teknis referensi. Semua klaim input profil teknis yang direferensikan harus muncul dalam klaim tampilan profil teknis referensi.

ValidasiClaimsExchange

Elemen ValidasiClaimsExchange berisi elemen berikut:

Elemen	Kemunculan	Deskripsi
`ValidationClaimsExchangeTechnicalProfile`	1:n	Profil teknis yang akan digunakan untuk memvalidasi beberapa atau semua klaim tampilan dari profil teknis referensi.

Elemen ValidationClaimsExchangeTechnicalProfile berisi atribut berikut:

Atribut	Wajib	Deskripsi
`TechnicalProfileReferenceId`	Ya	Pengidentifikasi profil teknis yang sudah ditentukan dalam kebijakan atau kebijakan induk.

Elemen ValidationClaimsExchangeTechnicalProfile berisi elemen berikut:

Elemen	Kemunculan	Deskripsi
`Preconditions`	0:1	Daftar prakondisi yang harus dipenuhi agar profil teknis validasi dapat dijalankan.

Elemen Prakondisi berisi atribut berikut:

Atribut	Wajib	Deskripsi
`Type`	Ya	Jenis pemeriksaan atau kueri yang akan dilakukan untuk prakondisi. Nilai yang mungkin: `ClaimsExist` atau `ClaimEquals`. `ClaimsExist` menentukan bahwa tindakan harus dilakukan jika klaim yang ditentukan ada dalam kumpulan klaim pengguna saat ini. `ClaimEquals` menentukan bahwa tindakan harus dilakukan jika klaim yang ditentukan ada dan nilainya setara dengan nilai yang ditentukan.
`ExecuteActionsIf`	Ya	Menunjukkan apakah tindakan dalam prakondisi harus dilakukan jika pengujian benar atau salah.

Elemen Prakondisi berisi elemen berikut:

Elemen	Kemunculan	Deskripsi
`Value`	1:n	Data yang digunakan oleh pemeriksaan. Jika jenis pemeriksaan ini adalah `ClaimsExist`, bidang ini menentukan ClaimTypeReferenceId untuk dikueri. Jika jenis pemeriksaan ini adalah `ClaimEquals`, bidang ini menentukan ClaimTypeReferenceId untuk dikueri. Tentukan nilai yang akan diperiksa dalam elemen nilai lain.
`Action`	1:1	Tindakan yang harus diambil jika pemeriksaan prakondisi dalam langkah orkestrasi adalah benar. Nilai Tindakan ditetapkan ke `SkipThisValidationTechnicalProfile`, yang menentukan bahwa profil teknis validasi terkait tidak boleh dijalankan.

Contoh berikut mengirim dan memverifikasi alamat email menggunakan profil teknis 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>

Contoh berikut mengirimkan kode baik dalam email atau SMS berdasarkan pilihan pengguna atas klaim mfaType dengan prakondisi.

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

Mereferensikan kontrol tampilan

Kontrol tampilan direferensikan dalam klaim tampilan dari profil teknis yang dinyatakan sendiri.

Misalnya:

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

Langkah berikutnya

Untuk sampel cara menggunakan kontrol tampilan, lihat: