Menambahkan konektor API ke alur pengguna

Berlaku untuk: Penyewa Tenaga Kerja Penyewa eksternal (pelajari lebih lanjut)

Untuk menggunakan konektor API, pertama-tama Anda membuat konektor API lalu mengaktifkannya dalam alur pengguna.

Penting

• Mulai 12 Juli 2021, jika pelanggan Microsoft Entra B2B menyiapkan integrasi Google baru untuk digunakan dengan pendaftaran layanan mandiri untuk aplikasi kustom atau lini bisnis mereka, autentikasi dengan identitas Google tidak akan berfungsi hingga autentikasi dipindahkan ke tampilan web sistem. Pelajari selengkapnya.
• Mulai 30 September 2021, Google menghentikan dukungan masuk dengan tampilan web tersemat. Jika aplikasi Anda mengautentikasi pengguna dengan tampilan web yang disematkan dan Anda menggunakan federasi Google dengan Azure AD B2C atau Microsoft Entra B2B untuk undangan pengguna eksternal atau pendaftaran layanan mandiri, pengguna Google Gmail tidak akan dapat mengautentikasi. Pelajari selengkapnya.

Membuat konektor API

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Pengguna.

2. Telusuri Ikhtisar Identitas>Eksternal Identitas.>

3. Pilih Semua konektor API, lalu pilih Konektor API Baru.

   

4. Berikan nama tampilan untuk panggilan tersebut. Misalnya, Periksa status persetujuan.

5. Berikan URL titik akhir untuk panggilan API.

6. Pilih Jenis autentikasi dan konfigurasikan informasi autentikasi untuk memanggil API Anda. Pelajari cara Mengamankan Konektor API Anda.

   

7. Pilih Simpan.

Permintaan dikirim ke API Anda

Konektor API terwujud sebagai permintaan HTTP POST, mengirim atribut pengguna ('klaim') sebagai pasangan kunci-nilai dalam isi JSON. Atribut diserialisasikan mirip dengan properti pengguna Microsoft Graph.

Contoh permintaan

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Hanya properti pengguna dan atribut kustom yang tercantum dalam Ikhtisar>Identitas>Eksternal>Identitas Kustom yang pengalaman atribut pengguna kustom yang tersedia untuk dikirim dalam permintaan.

Atribut kustom ada dalam format extension_<extensions-app-id>_AttributeName dalam direktori. API Anda akan mengharapkan untuk menerima klaim dalam format serial yang sama. Untuk informasi selengkapnya tentang atribut kustom, lihat menentukan atribut kustom untuk alur pendaftaran layanan mandiri.

Selain itu, klaim biasanya dikirim di semua permintaan:

• Lokal UI ('ui_locales') - Lokal pengguna akhir seperti yang dikonfigurasi pada perangkat mereka. Ini dapat digunakan oleh API Anda untuk mengembalikan respons internasional.

• Alamat Email ('email') atau identitas ('identitas') - klaim ini dapat digunakan oleh API Anda untuk mengidentifikasi pengguna akhir yang mengautentikasi aplikasi.

Penting

Jika klaim tidak memiliki nilai pada saat titik akhir API dipanggil, klaim tidak akan dikirim ke API. API Anda harus dirancang untuk secara eksplisit untuk memeriksa dan menangani kasus di mana klaim tidak ada dalam permintaan.

Mengaktifkan konektor API dalam alur pengguna

Ikuti langkah-langkah ini untuk menambahkan konektor API ke alur pengguna pendaftaran layanan mandiri.

1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Pengguna.

2. Telusuri Ikhtisar Identitas>Eksternal Identitas.>

3. Pilih Alur pengguna, lalu pilih alur pengguna yang ingin Anda tambahkan konektor API.

4. Pilih konektor API, lalu pilih titik akhir API yang ingin Anda panggil pada langkah-langkah berikut ini dalam alur pengguna:

   • Setelah bergabung dengan IdP saat mendaftar
   • Sebelum membuat pengguna

   

5. Pilih Simpan.

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, atau ID Microsoft Entra). Langkah ini mendahului halaman kumpulan atribut, yang merupakan formulir yang disajikan kepada pengguna untuk mengumpulkan atribut pengguna.

Contoh permintaan dikirim ke API pada langkah ini

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "lastName":"Smith",
 "ui_locales":"en-US"
}

Klaim yang tepat dikirim ke API bergantung pada informasi mana yang disediakan oleh penyedia identitas. 'email' selalu dikirim.

Jenis respons yang diharapkan dari API web pada langkah ini

Saat API web menerima permintaan HTTP dari ID Microsoft Entra selama alur pengguna, API web dapat mengembalikan respons ini:

• Respons kelanjutan
• Respons pemblokiran

Respons kelanjutan

Respons kelanjutan menunjukkan bahwa alur pengguna harus berlanjut ke langkah berikutnya: halaman koleksi atribut.

Dalam respons kelanjutan, API dapat mengembalikan klaim. Jika klaim dikembalikan oleh API, klaim akan melakukan hal berikut ini:

• Isi bidang input di halaman pengumpulan atribut.

Lihat contoh respons kelanjutan.

Respons Pemblokiran

Respons pemblokiran keluar dari alur pengguna. Respons dapat dengan sengaja dikeluarkan oleh API untuk menghentikan kelanjutan alur pengguna dengan menampilkan halaman blok kepada pengguna. Halaman blok menampilkan userMessage yang disediakan oleh API.

Lihat contoh respons pemblokiran.

Sebelum membuat pengguna

Konektor API pada langkah ini dalam proses pendaftaran dipanggil setelah halaman koleksi atribut, jika ada yang disertakan. Langkah ini selalu dipanggil sebelum akun pengguna dibuat di ID Microsoft Entra.

Contoh permintaan dikirim ke API pada langkah ini

POST <API-endpoint>
Content-type: application/json

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ // Sent for Google, Facebook, and Email One Time Passcode identity providers 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "jobTitle":"Supplier",
 "streetAddress":"1000 Microsoft Way",
 "city":"Seattle",
 "postalCode": "12345",
 "state":"Washington",
 "country":"United States",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "ui_locales":"en-US"
}

Klaim yang tepat dikirim ke API bergantung pada informasi mana yang dikumpulkan dari pengguna atau disediakan oleh penyedia identitas.

Jenis respons yang diharapkan dari API web pada langkah ini

Saat API web menerima permintaan HTTP dari ID Microsoft Entra selama alur pengguna, API web dapat mengembalikan respons ini:

• Respons kelanjutan
• Respons pemblokiran
• Respons validasi

Respons kelanjutan

Respons kelanjutan menunjukkan bahwa alur pengguna harus berlanjut ke langkah berikutnya: membuat pengguna di direktori.

Dalam respons kelanjutan, API dapat mengembalikan klaim. Jika klaim dikembalikan oleh API, klaim akan melakukan hal berikut ini:

• Mengambil alih nilai apa pun yang telah ditetapkan ke klaim dari halaman koleksi atribut.

Lihat contoh respons kelanjutan.

Respons Pemblokiran

Respons pemblokiran keluar dari alur pengguna. Respons dapat dengan sengaja dikeluarkan oleh API untuk menghentikan kelanjutan alur pengguna dengan menampilkan halaman blok kepada pengguna. Halaman blok menampilkan userMessage yang disediakan oleh API.

Lihat contoh respons pemblokiran.

Respons kesalahan validasi

Saat API merespons dengan respons kesalahan validasi, alur pengguna tetap berada di halaman pengumpulan atribut, dan userMessage ditampilkan kepada pengguna. Kemudian pengguna dapat mengedit dan mengirim ulang formulir. Jenis respons ini dapat digunakan untuk validasi input.

Lihat contoh respons kesalahan validasi.

Contoh respons

Contoh respons kelanjutan

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

Parameter	Tipe	Wajib	Deskripsi
versi	String	Ya	Versi API Anda.
tindakan	String	Ya	Nilai harus Continue.
<builtInUserAttribute>	<attribute-type>	No	Nilai dapat disimpan di direktori jika dipilih sebagai Klaim untuk menerima konfigurasi konektor API dan Atribut pengguna untuk alur pengguna. Nilai dapat dikembalikan dalam token jika dipilih sebagai Klaim aplikasi.
<extension_{extensions-app-id}_CustomAttribute>	<attribute-type>	No	Klaim tidak perlu berisi _<extensions-app-id>_, itu opsional. Nilai yang dikembalikan dapat menimpa nilai yang dikumpulkan dari pengguna.

Contoh respons pemblokiran

HTTP/1.1 200 OK
Content-type: application/json

{
    "version": "1.0.0",
    "action": "ShowBlockPage",
    "userMessage": "There was an error with your request. Please try again or contact support.",
}

Parameter	Tipe	Wajib	Deskripsi
versi	String	Ya	Versi API Anda.
tindakan	String	Ya	Nilai harus ShowBlockPage
userMessage	String	Ya	Pesan untuk ditampilkan kepada pengguna.

Pengalaman pengguna akhir terhadap respons pemblokiran

Contoh respons kesalahan validasi

HTTP/1.1 400 Bad Request
Content-type: application/json

{
    "version": "1.0.0",
    "status": 400,
    "action": "ValidationError",
    "userMessage": "Please enter a valid Postal Code.",
}

Parameter	Tipe	Wajib	Deskripsi
versi	String	Ya	Versi API Anda.
tindakan	String	Ya	Nilai harus ValidationError.
status	Bilangan bulat/Untai	Ya	Harus bernilai 400, atau "400" untuk respons KesalahanValidasi.
userMessage	String	Ya	Pesan untuk ditampilkan kepada pengguna.

Catatan

Kode status HTTP harus "400" selain nilai "status" dalam isi respons.

Pengalaman pengguna akhir dengan respons kesalahan validasi

Praktik terbaik dan cara memecahkan masalah

Menggunakan fungsi cloud tanpa server

Fungsi tanpa server, seperti pemicu HTTP di Azure Functions, menyediakan cara membuat titik akhir API untuk digunakan dengan konektor API. Anda dapat menggunakan fungsi cloud tanpa server untuk, misalnya, melakukan logika validasi dan membatasi pendaftaran ke domain email tertentu. Fungsi cloud tanpa server juga dapat memanggil dan meminta API web lainnya, penyimpanan data, serta layanan cloud lainnya untuk skenario yang lebih kompleks.

Praktik terbaik

Pastikan bahwa:

• API Anda mengikuti permintaan API dan kontrak respons seperti yang diuraikan di atas.
• Titik akhir URL konektor API menunjuk ke titik akhir API yang benar.
• API Anda secara eksplisit memeriksa nilai null dari klaim yang diterima, yang menentukan API tersebut.
• API Anda menerapkan metode autentikasi yang diuraikan dalam mengamankan konektor API Anda.
• API Anda merespons secepat mungkin untuk memastikan pengalaman pengguna yang lancar.
  • ID Microsoft Entra menunggu maksimal 20 detik untuk menerima respons. Jika tidak ada yang diterima, itu membuat satu upaya lagi (coba lagi) saat memanggil API Anda.
  • Jika menggunakan fungsi tanpa server atau layanan web yang dapat diskalakan, gunakan paket hosting yang membuat API tetap "terjaga" atau "hangat" dalam produksi. Untuk Azure Functions, sebaiknya gunakan minimal paket Premium.
• Pastikan API Anda dalam ketersediaan yang tinggi.
• Pantau dan optimalkan kinerja API, database, atau dependensi API hilir lainnya.
• Titik akhir Anda harus mematuhi Persyaratan keamanan Microsoft Entra TLS dan cipher. Untuk informasi lebih lanjut, lihat Persyaratan TLS dan cipher suite.

Gunakan logging

Secara umum, sangat berguna untuk menggunakan alat logging yang diaktifkan oleh layanan API web Anda, seperti Wawasan aplikasi, untuk memantau API Anda terhadap kode kesalahan, pengecualian, dan performa yang buruk.

• Pantau kode status HTTP yang bukan HTTP 200 atau 400.
• Kode status HTTP 401 atau 403 biasanya menunjukkan ada masalah dengan autentikasi Anda. Periksa kembali lapisan autentikasi API Anda dan konfigurasi yang sesuai di konektor API.
• Gunakan tingkat logging yang lebih agresif (misalnya "trace" atau "debug") dalam pengembangan jika diperlukan.
• Pantau API Anda untuk waktu respons yang lama.

Langkah berikutnya

• Pelajari cara menambahkan alur kerja persetujuan kustom ke pendaftaran layanan mandiri
• Mulai dengan sampel mulai cepat kami.