Menggunakan konektor API untuk menyesuaikan dan memperluas alur pengguna pendaftaran dan kebijakan kustom dengan sumber data identitas eksternal

  • Artikel

Sebelum memulai, gunakan pemilih Pilih jenis kebijakan untuk memilih jenis kebijakan yang Anda siapkan. Azure Active Directory B2C menawarkan dua metode untuk menentukan cara pengguna berinteraksi dengan aplikasi Anda: melalui alur pengguna yang telah ditentukan sebelumnya atau melalui kebijakan kustom yang sepenuhnya dapat dikonfigurasi. Langkah yang diperlukan dalam artikel ini berbeda untuk setiap metode.

Gambaran Umum

Sebagai pengembang atau administrator TI, Anda dapat menggunakan konektor API untuk mengintegrasikan alur pendaftaran pengguna Anda dengan REST API untuk menyesuaikan pengalaman pendaftaran dan mengintegrasikan dengan sistem eksternal. Misalnya, dengan konektor API, Anda dapat:

  • Memvalidasi data input pengguna. Validasi terhadap data pengguna yang rusak atau tidak valid. Misalnya, Anda dapat memvalidasi data yang disediakan pengguna terhadap data yang ada di penyimpanan data eksternal atau daftar nilai yang diizinkan. Jika tidak valid, Anda dapat meminta pengguna untuk memberikan data yang valid atau memblokir pengguna agar tidak melanjutkan alur pendaftaran.
  • Memverifikasi identitas pengguna. Gunakan layanan verifikasi identitas atau sumber data identitas eksternal untuk menambahkan tingkat keamanan ekstra ke keputusan pembuatan akun.
  • Mengintegrasikan dengan alur kerja persetujuan kustom. Sambungkan ke sistem persetujuan kustom untuk mengelola dan membatasi pembuatan akun.
  • Menambahkan token dengan atribut dari sumber eksternal. Perkaya token dengan atribut tentang pengguna dari sumber yang berada di luar Azure AD B2C seperti sistem cloud, penyimpanan pengguna kustom, sistem izin kustom, layanan identitas warisan, dan banyak lagi.
  • Menimpa atribut pengguna. Format ulang atau tetapkan nilai ke atribut yang dikumpulkan dari pengguna. Misalnya, jika pengguna memasukkan nama depan dalam huruf kecil semua atau huruf besar semua, Anda dapat memformat nama hanya dengan huruf pertama yang dikapitalisasi.
  • Menjalankan logika bisnis kustom. Anda dapat memicu peristiwa hilir di sistem cloud Anda untuk mengirim pemberitahuan push, memperbarui database perusahaan, mengelola izin, mengaudit database, dan melakukan tindakan kustom lainnya.

Konektor API menyediakan Azure AD B2C dengan informasi yang diperlukan untuk memanggil titik akhir API dengan menentukan URL titik akhir HTTP dan autentikasi untuk panggilan API. Setelah mengonfigurasi konektor API, Anda dapat mengaktifkannya untuk langkah tertentu dalam alur pengguna. Ketika pengguna mencapai langkah tersebut dalam alur pendaftaran, konektor API dipanggil dan terlaksana sebagai permintaan HTTP POST ke API Anda, mengirim informasi pengguna ("klaim") sebagai pasangan kunci-nilai dalam isi JSON. Respons API dapat memengaruhi eksekusi alur pengguna. Misalnya, respons API dapat memblokir pengguna agar tidak mendaftar, meminta pengguna untuk memasukkan kembali informasi, atau menimpa atribut pengguna.

Di mana Anda dapat mengaktifkan konektor API dalam alur pengguna

Ada tiga tempat dalam alur pengguna tempat Anda dapat mengaktifkan konektor API:

  • Setelah bergabung dengan IdP selama pendaftaran - hanya berlaku untuk pengalaman pendaftaran
  • Sebelum membuat pengguna - hanya berlaku untuk pengalaman pendaftaran
  • Sebelum mengirim token (pratinjau) - berlaku untuk pendaftaran dan rincian masuk

Setelah bergabung dengan IdP saat mendaftar

Konektor API pada langkah ini dalam proses pendaftaran dipanggil segera setelah pengguna mengautentikasi dengan penyedia identitas (seperti Google, Facebook, dan ID Microsoft Entra). Langkah ini mendahului halaman kumpulan atribut, yang merupakan formulir yang disajikan kepada pengguna untuk mengumpulkan atribut pengguna. Langkah ini tidak dipanggil jika pengguna mendaftar dengan akun lokal. Berikut ini adalah contoh skenario konektor API yang mungkin Anda aktifkan pada langkah berikut:

  • Gunakan email atau identitas federasi yang disediakan pengguna untuk mencari klaim dalam sistem yang ada. Kembalikan klaim ini dari sistem yang ada, isi terlebih dahulu halaman pengumpulan atribut, dan buat klaim tersebut tersedia untuk dikembalikan dalam token.
  • Terapkan izin atau pemblokiran berdasarkan identitas sosial.

Sebelum membuat pengguna

Konektor API pada langkah ini dalam proses pendaftaran dipanggil setelah halaman pengumpulan atribut, jika ada yang disertakan. Langkah ini selalu dipanggil sebelum akun pengguna dibuat. Berikut ini adalah contoh skenario yang mungkin Anda aktifkan saat ini selama pendaftaran:

  • Validasi data input pengguna dan minta pengguna untuk mengirim ulang data.
  • Blokir pendaftaran pengguna berdasarkan data yang dimasukkan oleh pengguna.
  • Verifikasi identitas pengguna.
  • Kueri sistem eksternal untuk data yang sudah ada tentang pengguna untuk mengembalikannya dalam token aplikasi atau menyimpannya di ID Microsoft Entra.

Sebelum mengirim token (pratinjau)

Catatan

Fitur ini berada dalam pratinjau publik.

Konektor API pada langkah ini dalam proses pendaftaran atau rincian masuk dipanggil sebelum token dikeluarkan. Berikut ini adalah contoh skenario yang dapat Anda aktifkan pada langkah ini:

  • Memperkaya token dengan atribut tentang pengguna dari sumber yang berbeda dari direktori termasuk sistem identitas warisan, sistem HR, penyimpanan pengguna eksternal, dan banyak lagi.
  • Memperkaya token dengan atribut grup atau peran yang Anda simpan dan kelola di sistem izin Anda sendiri.
  • Menerapkan transformasi atau manipulasi klaim ke nilai klaim di direktori.

IEF, yang mendasari Azure Active Directory B2C (Azure AD B2C), dapat diintegrasikan dengan RESTful API dalam perjalanan pengguna. Artikel ini menunjukkan cara membuat perjalanan pengguna yang berinteraksi dengan layanan RESTful menggunakan profil teknis RESTful.

Menggunakan Azure AD B2C, Anda dapat menambahkan logika bisnis Anda sendiri ke perjalanan pengguna dengan menghubungi layanan RESTful Anda sendiri. IEF dapat mengirim dan menerima data dari layanan RESTful Anda untuk bertukar klaim. Sebagai contoh, Anda dapat:

  • Gunakan sumber data identitas eksternal untuk memvalidasi data input pengguna. Misalnya, Anda dapat memverifikasi bahwa alamat email yang diberikan oleh pengguna ada di database pelanggan Anda, dan jika tidak, akan muncul kesalahan. Anda juga dapat menganggap konektor API sebagai cara mendukung webhook keluar karena panggilan dilakukan ketika suatu peristiwa terjadi, misalnya, pendaftaran.
  • Mengklaim proses. Jika pengguna memasukkan nama depan mereka dalam huruf kecil semua atau huruf besar semua, REST API Anda dapat memformat nama hanya dengan huruf pertama yang dikapitalisasi dan mengembalikannya ke Azure AD B2C. Namun, saat menggunakan kebijakan khusus, sebaiknya panggil ClaimsTransformations daripada RESTful API.
  • Perkaya data pengguna melalui integrasi lebih lanjut dengan aplikasi lini bisnis perusahaan. Layanan RESTful Anda bisa menerima alamat email pengguna, mengkueri database pelanggan, dan mengembalikan nomor loyalitas pengguna ke Azure AD B2C. Kemudian klaim pengembalian dapat disimpan di akun Microsoft Entra pengguna, dievaluasi dalam langkah-langkah orkestrasi berikutnya, atau disertakan dalam token akses.
  • Menjalankan logika bisnis kustom. Anda dapat mengirim pemberitahuan push, memperbarui database perusahaan, menjalankan proses migrasi pengguna, mengelola izin, mengaudit database, dan melakukan alur kerja lainnya.

Diagram pertukaran klaim layanan RESTful

Catatan

Jika ada respons lambat atau tidak ada respons dari layanan RESTful ke Azure AD B2C, batas waktunya adalah 30 detik dan hitungan coba lagi adalah dua kali (artinya ada total 3 percobaan). Saat ini, Anda tidak dapat mengonfigurasi pengaturan waktu habis dan mencoba kembali jumlah.

Memanggil layanan RESTful

Interaksi ini mencakup pertukaran klaim informasi antara klaim REST API dan Azure AD B2C. Anda dapat merancang integrasi dengan layanan RESTful dengan cara berikut:

  • Profil teknis validasi. Panggilan ke layanan RESTful terjadi dalam profil teknis validasi dari profil teknis yang ditegaskan sendiri yang ditentukan, atau kontrol tampilan verifikasi dari tampilan kontrol. Profil teknis validasi memvalidasi data yang disediakan pengguna sebelum perjalanan pengguna diteruskan. Dengan profil teknis validasi, Anda dapat:

    • Kirim klaim ke REST API Anda.
    • Validasi klaim, dan berikan pesan kesalahan kustom yang ditampilkan kepada pengguna.
    • Kirim kembali klaim dari REST API ke langkah orkestrasi berikutnya.

  • Pertukaran klaim. Pertukaran klaim langsung dapat dikonfigurasi dengan memanggil profil teknis REST API langsung dari langkah orkestrasi perjalanan pengguna. Definisi ini terbatas pada:

    • Kirim klaim ke REST API Anda.
    • Validasi klaim, dan berikan pesan kesalahan kustom yang dikembalikan ke aplikasi.
    • Kirim kembali klaim dari REST API ke langkah orkestrasi berikutnya.

Anda dapat menambahkan panggilan REST API pada setiap langkah dalam perjalanan pengguna yang ditentukan oleh kebijakan kustom. Misalnya, Anda dapat memanggil REST API:

  • Selama masuk, tepat sebelum Azure AD B2C memvalidasi info masuk.
  • Segera setelah masuk.
  • Sebelum Azure AD B2C membuat akun baru di direktori.
  • Setelah Azure AD B2C membuat akun baru di direktori.
  • Sebelum Azure AD B2C mengeluarkan token akses.

Validasi pengumpulan profil teknis

Mengirim data

Dalam profil teknis RESTful, elemen InputClaims berisi daftar klaim yang akan dikirim ke layanan RESTful Anda. Anda dapat memetakan nama klaim Anda ke nama yang ditentukan dalam layanan RESTful, mengatur nilai default, dan menggunakan penyelesai klaim.

Anda dapat mengonfigurasi bagaimana klaim input dikirim ke penyedia klaim RESTful dengan menggunakan atribut SendClaimsIn. Nilai yang mungkin adalah:

  • Isi, dikirim dalam isi permintaan HTTP POST dalam format JSON.
  • Formulir, dikirim dalam isi permintaan HTTP POST dalam format nilai kunci terpisah ampersand '&'.
  • Header, dikirim di header permintaan HTTP GET.
  • QueryString, dikirim dalam string kueri permintaan HTTP GET.

Ketika opsi Isi dikonfigurasi, profil teknis REST API memungkinkan Anda untuk mengirim payload JSON yang kompleks ke titik akhir. Untuk informasi selengkapnya, lihat Mengirim payload JSON.

Menerima data

Elemen OutputClaims dari profil teknis RESTful berisi daftar klaim yang dikembalikan oleh REST API. Anda mungkin perlu memetakan nama klaim yang ditentukan dalam kebijakan Anda ke nama yang ditentukan di REST API. Anda juga dapat menyertakan klaim yang tidak dikembalikan oleh IdP REST API, selama Anda mengatur atribut DefaultValue.

Klaim output yang dipilah oleh penyedia klaim RESTful selalu ingin memilah respons Isi JSON yang datar, seperti:

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

Klaim output akan terlihat seperti cuplikan xml berikut:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

Menangani nilai null

Nilai null dalam database digunakan ketika nilai dalam kolom tidak diketahui atau hilang. Jangan sertakan kunci JSON dengan null nilai. Dalam contoh berikut, email menampilkan nilai null:

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

Saat elemen adalah nol, baik:

  • Hapus pasangan kunci-nilai dari JSON.
  • Menghasilkan nilai yang sesuai dengan jenis data klaim Azure Active Directory B2C. Misalnya, untuk jenis data string, menghasilkan string kosong "". Untuk jenis data integer, menghasilkan nilai nol 0. Untuk jenis data dateTime, menghasilkan nilai minimum 1970-00-00T00:00:00.0000000Z.

Contoh berikut menunjukkan cara menangani nilai null. Email dihilangkan dari JSON:

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

Menguraikan isi JSON berlapis

Untuk mengurai respons isi JSON berlapis, atur metadata ResolveJsonPathsInJsonTokens ke benar. Dalam klaim output, atur PartnerClaimType ke elemen jalur JSON yang ingin Anda outputkan.

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

Klaim output akan terlihat seperti cuplikan xml berikut:

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

Melokalisasi REST API

Dalam profil teknis RESTful, Anda mungkin ingin mengirim bahasa/lokal sesi saat ini, dan jika perlu, ajukan pesan kesalahan lokal. Menggunakan penyelesai klaim, Anda dapat mengirim klaim kontekstual, seperti bahasa pengguna. Contoh berikut menunjukkan profil teknis RESTful dengan skenario ini.

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

Menangani pesan kesalahan

REST API Anda mungkin perlu mengembalikan pesan kesalahan, seperti "Pengguna tidak ditemukan di sistem CRM." Jika terjadi kesalahan, REST API harus mengembalikan pesan kesalahan HTTP 409 (Kode status respons konflik). Untuk informasi selengkapnya, lihat profil teknis RESTful.

Perilaku ini hanya dapat dicapai dengan memanggil profil teknis REST API dari profil teknis validasi. Memungkinkan pengguna memperbaiki data di halaman dan menjalankan validasi lagi setelah pengiriman halaman.

Jika Anda mereferensikan profil teknis REST API langsung dari perjalanan pengguna, pengguna dialihkan kembali ke aplikasi pihak yang mengandalkan dengan pesan kesalahan yang relevan.

Pengembangan REST API Anda

REST API Anda dapat dikembangkan pada platform apa pun dan ditulis dalam bahasa pemrograman apa pun, asalkan aman dan dapat mengirim dan menerima klaim dalam format JSON.

Permintaan ke layanan REST API Anda berasal dari server Azure AD B2C. Layanan REST API harus diterbitkan ke titik akhir HTTPS yang dapat diakses publik. Panggilan REST API akan tiba dari alamat IP pusat data Azure.

Anda dapat menggunakan fungsi cloud tanpa server, seperti pemicu HTTP di Azure Functions untuk kemudahan pengembangan.

Anda harus mendesain layanan REST API Anda dan komponen dasarnya (seperti database dan sistem file) menjadi sangat tersedia.

Penting

Titik akhir Anda harus mematuhi persyaratan keamanan Azure AD B2C. Versi dan cipher TLS yang lebih lama tidak digunakan lagi. Untuk informasi lebih lanjut, lihat Persyaratan Azure AD B2C TLS dan cipher suite.

Langkah berikutnya

Lihat artikel berikut ini untuk contoh penggunaan profil teknis RESTful: