ContentDefinitions

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.

Anda dapat menyesuaikan tampilan dan nuansa profil teknis yang ditegaskan sendiri. Azure Active Directory B2C (Azure AD B2C) menjalankan kode di browser pelanggan Anda dan menggunakan pendekatan modern yang disebut Cross-Origin Resource Sharing (CORS).

Untuk menyesuaikan antarmuka pengguna, Anda menentukan URL di elemen ContentDefinition dengan konten HTML yang dikustomisasi. Dalam profil teknis yang ditegaskan sendiri atau OrchestrationStep, Anda mengarahkan ke pengenal definisi konten tersebut. Definisi konten mungkin berisi elemen LocalizedResourcesReferences yang menentukan daftar sumber daya yang dilokalkan untuk dimuat. Azure AD B2C menggabungkan elemen antarmuka pengguna dengan konten HTML yang dimuat dari URL Anda lalu menampilkan halaman tersebut kepada pengguna.

Elemen ContentDefinitions berisi URL ke template HTML5 yang dapat digunakan dalam perjalanan pengguna. URI halaman HTML5 digunakan untuk langkah antarmuka pengguna tertentu. Misalnya, halaman masuk atau pendaftaran, reset kata sandi, atau kesalahan. Anda dapat memodifikasi tampilan dan nuansa dengan mengesampingkan LoadUri untuk file HTML5. Anda dapat membuat definisi konten baru sesuai dengan kebutuhan Anda. Elemen ini mungkin berisi referensi sumber daya yang di lokal, ke pengidentifikasi pelokalan yang ditentukan dalam elemen Pelokalan.

Contoh berikut menunjukkan pengidentifikasi definisi konten dan definisi sumber daya yang dilokalkan:

<ContentDefinition Id="api.localaccountsignup">
  <LoadUri>~/tenant/default/selfAsserted.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:selfasserted:1.1.0</DataUri>
  <Metadata>
    <Item Key="DisplayName">Local account sign up page</Item>
  </Metadata>
  <LocalizedResourcesReferences MergeBehavior="Prepend">
    <LocalizedResourcesReference Language="en" LocalizedResourcesReferenceId="api.localaccountsignup.en" />
    <LocalizedResourcesReference Language="es" LocalizedResourcesReferenceId="api.localaccountsignup.es" />
    ...

Metadata profil teknis yang menegaskan sendiri LocalAccountSignUpWithLogonEmail berisi pengenal definisi konten ContentDefinitionReferenceId yang disetel ke api.localaccountsignup

<TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
  <DisplayName>Email signup</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ContentDefinitionReferenceId">api.localaccountsignup</Item>
    ...
  </Metadata>
  ...

ContentDefinition

Elemen ContentDefinition berisi atribut berikut:

Atribut	Diperlukan	Deskripsi
Id	Ya	Pengidentifikasi untuk definisi konten. Nilainya ditentukan di bagian ID definisi konten nanti di laman ini.

Elemen ContentDefinition berisi elemen-elemen berikut:

Elemen	Kemunculan	Deskripsi
LoadUri	1:1	String yang berisi URL halaman HTML5 untuk definisi konten.
RecoveryUri	1:1	String yang berisi URL halaman HTML untuk menampilkan kesalahan yang berkaitan dengan definisi konten. Saat ini tidak digunakan, nilainya harus `~/common/default_page_error.html`.
DataUri	1:1	String yang berisi URL relatif dari file HTML yang memberikan pengalaman pengguna untuk memanggil langkah tersebut.
Metadata	0:1	Kumpulan pasangan kunci/nilai yang berisi metadata yang digunakan oleh definisi konten.
LocalizedResourcesReferences	0:1	Kumpulan referensi sumber daya yang dilokalkan. Gunakan elemen ini untuk menyesuaikan pelokalan antarmuka pengguna dan atribut klaim.

LoadUri

Elemen LoadUri digunakan untuk menentukan URL halaman HTML5 untuk definisi konten. Paket pemula kebijakan kustom Active Directory B2C dilengkapi dengan definisi konten yang menggunakan halaman HTML Active Directory B2C. LoadUri dimulai dengan ~, yang merupakan jalur relatif ke penyewa Active Directory B2C Anda.

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>~/tenant/templates/AzureBlue/unified.cshtml</LoadUri>
  ...
</ContentDefinition>

Anda dapat menyesuaikan antarmuka pengguna dengan templat HTML. Saat menggunakan templat HTML, berikan URL absolut. Contoh berikut mengilustrasikan definisi konten dengan templat HTML:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://your-storage-account.blob.core.windows.net/your-container/customize-ui.html</LoadUri>
  ...
</ContentDefinition>

DataUri

Elemen DataUri digunakan untuk menentukan pengidentifikasi halaman. Azure AD B2C menggunakan pengidentifikasi halaman untuk memuat dan memulai elemen antarmuka pengguna dan sisi klien JavaScript. Format nilainya adalah urn:com:microsoft:aad:b2c:elements:page-name:version. Tabel berikut ini mencantumkan pengidentifikasi halaman yang bisa Anda gunakan.

Pengidentifikasi halaman	Deskripsi
`globalexception`	Menampilkan halaman kesalahan ketika pengecualian atau kesalahan ditemui.
`providerselection`, `idpselection`	Mencantumkan IdP yang bisa dipilih pengguna pada saat masuk.
`unifiedssp`	Menampilkan formulir untuk masuk dengan akun lokal yang didasarkan pada alamat email atau nama pengguna. Nilai ini juga menyediakan tautan “fungsionalitas buat saya tetap masuk” dan “Lupa kata sandi Anda?”.
`unifiedssd`	Menampilkan formulir untuk masuk dengan akun lokal yang didasarkan pada alamat email atau nama pengguna. Pengenal halaman ini sudah tidak digunakan lagi. Gunakan `unifiedssp` pengidentifikasi halaman saja.
`multifactor`	Memverifikasi nomor telepon dengan menggunakan teks atau suara saat mendaftar atau masuk.
`selfasserted`	Menampilkan formulir untuk mengumpulkan data dari pengguna. Misalnya, memungkinkan pengguna untuk membuat atau memperbarui profil mereka.

Memilih tata letak halaman

Anda dapat mengaktifkan kode sisi klien JavaScript dengan memasukkan contract antara elements dan jenis halaman. Contohnya:urn:com:microsoft:aad:b2c:elements:contract:page-name:version

Bagian versi dari DataUri yang menentukan paket konten yang berisi HTML, CSS, dan JavaScript untuk elemen antarmuka pengguna dalam kebijakan Anda. Jika Anda bermaksud mengaktifkan kode sisi klien JavaScript, elemen yang Anda dasari javascript Anda harus tidak dapat diubah. Jika dapat diubah, perubahan apa pun dapat menyebabkan perilaku tak terduga di halaman pengguna Anda. Untuk mencegah masalah ini, terapkan penggunaan tata letak halaman dan tentukan versi tata letak halaman. Dengan melakukannya akan memastikan bahwa semua definisi konten yang menjadi dasar JavaScript Anda tidak dapat diubah. Bahkan jika Anda tidak bermaksud untuk mengaktifkan JavaScript, Anda masih perlu menentukan versi tata letak halaman untuk halaman Anda.

Contoh berikut menunjukkan DataUri dari selfasserted versi 1.2.0:

<!-- 
<BuildingBlocks> 
  <ContentDefinitions>-->
    <ContentDefinition Id="api.localaccountpasswordreset">
      <LoadUri>~/tenant/templates/AzureBlue/selfAsserted.cshtml</LoadUri>
      <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:1.2.0</DataUri>
      <Metadata>
        <Item Key="DisplayName">Local account change password page</Item>
      </Metadata>
    </ContentDefinition>
  <!-- 
  </ContentDefinitions> 
</BuildingBlocks> -->

Migrasi ke tata letak halaman

Untuk melakukan migrasi dari nilai DataUri lama (tanpa kontrak halaman) ke versi tata letak halaman, tambahkan kata contract diikuti oleh versi halaman. Gunakan tabel berikut untuk melakukan migrasi dari nilai DataUri lama ke versi tata letak halaman.

Nilai DataUri lama	Nilai DataUri baru
`urn:com:microsoft:aad:b2c:elements:globalexception:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1`
`urn:com:microsoft:aad:b2c:elements:globalexception:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1`
`urn:com:microsoft:aad:b2c:elements:idpselection:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1`
`urn:com:microsoft:aad:b2c:elements:selfasserted:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.7`
`urn:com:microsoft:aad:b2c:elements:selfasserted:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.7`
`urn:com:microsoft:aad:b2c:elements:unifiedssd:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:unifiedssd:1.2.1`
`urn:com:microsoft:aad:b2c:elements:unifiedssp:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.5`
`urn:com:microsoft:aad:b2c:elements:unifiedssp:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.5`
`urn:com:microsoft:aad:b2c:elements:multifactor:1.0.0`	`urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5`
`urn:com:microsoft:aad:b2c:elements:multifactor:1.1.0`	`urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5`

Contoh berikut menunjukkan pengidentifikasi definisi konten dan DataUri terkait dengan versi halaman terbaru:

<!-- 
<BuildingBlocks> -->
  <ContentDefinitions>
    <ContentDefinition Id="api.error">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:globalexception:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.idpselections">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.idpselections.signup">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:providerselection:1.2.1</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.signuporsignin">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:unifiedssp:2.1.7</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.selfasserted">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.selfasserted.profileupdate">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.localaccountsignup">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.localaccountpasswordreset">
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:selfasserted:2.1.14</DataUri>
    </ContentDefinition>
    <ContentDefinition Id="api.phonefactor">
      <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
      <DataUri>urn:com:microsoft:aad:b2c:elements:contract:multifactor:1.2.5</DataUri>
    </ContentDefinition>
  </ContentDefinitions>
<!-- 
</BuildingBlocks> -->

Metadata

Elemen Metadata berisi elemen berikut:

Elemen	Kemunculan	Deskripsi
Item	0:n	Metadata yang berkaitan dengan definisi konten.

Elemen Item dari elemen Metadata berisi atribut berikut:

Atribut	Diperlukan	Deskripsi
Kunci	Ya	Kunci metadata.

Kunci metadata

Definisi konten mendukung item metadata berikut:

Kunci	Diperlukan	Deskripsi
DisplayName	Tidak	String yang berisi nama definisi konten.

LocalizedResourcesReferences

Elemen LocalizedResources berisi elemen-elemen berikut:

Elemen	Kemunculan	Deskripsi
LocalizedResourcesReference	1:n	Daftar referensi sumber daya yang dilokalkan untuk definisi konten.

Elemen LocalizedResourcesReference berisi atribut berikut:

Atribut	Diperlukan	Deskripsi
Bahasa	Ya	String yang berisi bahasa yang didukung untuk kebijakan per RFC 5646 - Tag untuk Mengidentifikasi Bahasa.
LocalizedResourcesReferenceId	Ya	Pengidentifikasi elemen LocalizedResources.

Contoh berikut menunjukkan definisi konten pendaftaran atau masuk dengan referensi ke pelokalan untuk bahasa Inggris, Prancis, dan Spanyol:

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>~/tenant/default/unified.cshtml</LoadUri>
  <RecoveryUri>~/common/default_page_error.html</RecoveryUri>
  <DataUri>urn:com:microsoft:aad:b2c:elements:unifiedssp:1.0.0</DataUri>
  <Metadata>
    <Item Key="DisplayName">Signin and Signup</Item>
  </Metadata>
  <LocalizedResourcesReferences MergeBehavior="Prepend">
    <LocalizedResourcesReference Language="en" LocalizedResourcesReferenceId="api.signuporsignin.en" />
    <LocalizedResourcesReference Language="fr" LocalizedResourcesReferenceId="api.signuporsignin.rf" />
    <LocalizedResourcesReference Language="es" LocalizedResourcesReferenceId="api.signuporsignin.es" />
</LocalizedResourcesReferences>
</ContentDefinition>

Untuk mempelajari cara menambahkan dukungan pelokalan ke definisi konten Anda, lihat Pelokalan.

ID definisi konten

Atribut ID dari elemen ContentDefinition menentukan tipe halaman yang berkaitan dengan definisi konten. Elemen menentukan konteks yang akan diterapkan template HTML5/CSS kustom. Tabel berikut ini menjelaskan kumpulan ID definisi konten yang dikenali oleh Kerangka Kerja Pengalaman Identitas, dan tipe halaman yang terkait dengan ID tersebut. Anda dapat membuat definisi konten Anda sendiri dengan ID sesuai pilihan.

ID	Templat default	Deskripsi
api.error	exception.cshtml	Halaman kesalahan - Menampilkan halaman kesalahan saat pengecualian atau kesalahan ditemui.
api.idpselections	idpSelector.cshtml	Halaman pemilihan IdP - Mencantumkan IdP yang dapat dipilih pengguna pada saat masuk. Opsinya biasanya IdP perusahaan, IdP sosial seperti Facebook dan Google+, atau akun lokal.
api.idpselections.signup	idpSelector.cshtml	Pemilihan IdP untuk pendaftaran - Mencantumkan IdP yang dapat dipilih pengguna pada saat pendaftaran. Opsinya biasanya IdP perusahaan, IdP sosial seperti Facebook dan Google+, atau akun lokal.
api.localaccountpasswordreset	selfasserted.cshtml	Lupa halaman kata sandi - Menampilkan formulir yang harus diselesaikan pengguna untuk memulai reset kata sandi.
api.localaccountsignin	selfasserted.cshtml	Halaman masuk akun lokal - Menampilkan formulir untuk masuk dengan akun lokal yang didasarkan pada alamat email atau nama pengguna. Formulir dapat berisi kotak input teks dan kotak entri kata sandi.
api.localaccountsignup	selfasserted.cshtml	Halaman pendaftaran akun lokal - Menampilkan formulir untuk pendaftaran ke akun lokal yang didasarkan pada alamat email atau nama pengguna. Formulir dapat berisi berbagai kontrol input, seperti: kotak input teks, kotak entri kata sandi, tombol radio, kotak drop-down pilih tunggal, dan kotak centang multi-pilih.
api.phonefactor	multifaktor-1.0.0.cshtml	Halaman autentikasi multifaktor - Memverifikasi nomor telepon, dengan menggunakan teks atau suara, selama pendaftaran atau masuk.
api.selfasserted	selfasserted.cshtml	Halaman pendaftaran akun sosial - Menampilkan formulir yang harus diisi pengguna saat mereka mendaftar dengan menggunakan akun yang ada dari IdP sosial. Halaman ini mirip dengan halaman pendaftaran akun sosial sebelumnya, kecuali untuk bidang entri kata sandi.
api.selfasserted.profileupdate	updateprofile.cshtml	Halaman pembaruan profil - Menampilkan formulir yang dapat diakses pengguna untuk memperbarui profil mereka. Halaman ini mirip dengan halaman pendaftaran akun sosial, kecuali untuk bidang entri kata sandi.
api.signuporsignin	unified.cshtml	Halaman pendaftaran atau masuk terpadu - Menangani proses pendaftaran dan masuk pengguna. Pengguna dapat menggunakan IdP perusahaan, IdP sosial seperti Facebook atau Google+, atau akun lokal.

Langkah berikutnya

Untuk contoh mengkustomisasi antarmuka pengguna dengan menggunakan definisi konten, lihat:

Sesuaikan antarmuka pengguna aplikasi Anda menggunakan kebijakan kustom