Menambahkan konektor API untuk mendaftarkan alur pengguna

Penting

Berlaku mulai 1 Mei 2025, Azure AD B2C tidak akan lagi tersedia untuk dibeli untuk pelanggan baru. Pelajari lebih lanjut di FAQ kami.

Sebelum memulai, gunakan pemilih Pilih jenis kebijakan di bagian atas halaman ini 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.

Sebagai pengembang atau administrator TI, Anda dapat menggunakan konektor API untuk mengintegrasikan alur pengguna pendaftaran Anda dengan REST API untuk menyesuaikan pengalaman pendaftaran dan berintegrasi dengan sistem eksternal. Di akhir panduan ini, Anda akan dapat membuat alur pengguna Azure AD B2C yang berinteraksi dengan layanan REST API untuk memodifikasi pengalaman pendaftaran Anda.

Anda dapat membuat titik akhir API menggunakan salah satu sampel kami.

Dalam skenario ini, kita akan menambahkan kemampuan bagi pengguna untuk memasukkan nomor loyalitas ke halaman pendaftaran Azure AD B2C. REST API memvalidasi apakah kombinasi email dan nomor loyalitas dipetakan ke kode promosi. Jika REST API menemukan kode promosi untuk pengguna ini, maka akan dikembalikan ke Azure AD B2C. Akhirnya, kode promosi akan dimasukkan ke dalam klaim token agar dapat digunakan oleh aplikasi.

Anda juga dapat merancang interaksi sebagai langkah orkestrasi. Ini cocok ketika REST API tidak akan memvalidasi data di layar, dan selalu mengembalikan klaim. Untuk informasi selengkapnya, lihat Panduan: Mengintegrasikan pertukaran klaim REST API dalam perjalanan pengguna Azure AD B2C Anda sebagai langkah orkestrasi.

Prasyarat

Buat alur pengguna agar pengguna dapat mendaftar dan masuk ke aplikasi Anda.
Daftarkan aplikasi web.

Selesaikan langkah-langkah dalam Mulai menggunakan kebijakan kustom di Active Directory B2C. Tutorial ini memandu Anda cara memperbarui file kebijakan kustom untuk menggunakan konfigurasi penyewa Azure AD B2C Anda.
Daftarkan aplikasi web.

Membuat konektor API

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

Masuk ke portal Azure.
Di bawah layanan Azure, pilih Azure AD B2C.
Pilih konektor API, lalu pilih Konektor API baru.
Berikan nama tampilan untuk panggilan tersebut. Misalnya, Validasi informasi pengguna.
Berikan URL titik akhir untuk panggilan API.
Pilih Jenis autentikasi dan konfigurasikan informasi autentikasi untuk memanggil API Anda. Pelajari cara Mengamankan Konektor API Anda.
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": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "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",
 "step": "<step-name>",
 "client_id":"00001111-aaaa-2222-bbbb-3333cccc4444",
 "ui_locales":"en-US"
}

Hanya properti pengguna dan atribut kustom yang terdaftar dalam pengalaman Atribut Pengguna> yang tersedia untuk dikirim dalam permintaan.

Atribut kustom ada dalam format extension_<extensions-app-id>_CustomAttribute di direktori. API Anda akan mengharapkan untuk menerima klaim dalam format serial yang sama. Untuk informasi selengkapnya tentang atribut kustom, lihat Menentukan atribut kustom di Azure AD B2C.

Selain itu, klaim ini 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.
Langkah ('langkah') - Langkah atau titik pada alur pengguna tempat konektor API dipanggil. Nilai meliputi:
- PostFederationSignup - sesuai dengan "Setelah berfederasi dengan penyedia identitas selama pendaftaran"
- PostAttributeCollection - sesuai dengan "Sebelum membuat pengguna"
- PreTokenIssuance - sesuai dengan "Sebelum mengirim token (pratinjau)". Pelajari selengkapnya tentang langkah ini
ID Klien ('client_id') - Nilai appId dari aplikasi yang sedang diautentikasi oleh pengguna akhir dalam alur pengguna. Ini bukan aplikasi pengelola sumber daya appId yang terdapat dalam token akses.
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.

Masuk ke portal Azure.
Di bawah layanan Azure, pilih Azure AD B2C.
Pilih Alur pengguna, lalu pilih alur pengguna yang ingin Anda tambahkan konektor API.
Pilih konektor API, lalu pilih titik akhir API yang ingin Anda panggil pada langkah-langkah berikut ini dalam alur pengguna:
- Setelah menghubungkan dengan penyedia identitas saat mendaftar
- Sebelum membuat pengguna
- Sebelum mengirim token (pratinjau)
Pilih Simpan.

Langkah-langkah ini hanya ada untuk Mendaftar dan masuk (Disarankan) dan Daftar (Disarankan) tetapi hanya berlaku untuk bagian pendaftaran dari pengalaman.

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.

Contoh permintaan dikirim ke API pada langkah ini

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [ 
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "givenName":"John",
 "surname":"Smith",
 "step": "PostFederationSignup",
 "client_id":"<guid>",
 "ui_locales":"en-US"
}

Klaim yang tepat yang dikirim ke API bergantung pada informasi yang disediakan oleh penyedia identitas. 'email' itu 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:

Tanggapan Lanjutan
Respons pemblokiran

Tanggapan Lanjutan

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:

Mengisi otomatis bidang input di halaman koleksi atribut.

Lihat contoh respons kelanjutan.

Tanggapan Pemblokiran

Respons yang memblokir keluar dari aliran 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.

Contoh permintaan dikirim ke API pada langkah ini

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

{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "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",
 "step": "PostAttributeCollection",
 "client_id":"00001111-aaaa-2222-bbbb-3333cccc4444",
 "ui_locales":"en-US"
}

Klaim yang dikirim ke API bergantung pada informasi 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:

Tanggapan Lanjutan
Respons pemblokiran
Respons validasi

Tanggapan Lanjutan

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 disediakan oleh pengguna di halaman pengumpulan atribut.

Untuk menulis klaim ke direktori pada pendaftaran yang seharusnya tidak dikumpulkan dari pengguna, Anda masih harus memilih klaim di bawah Atribut pengguna dari alur pengguna, yang secara default akan meminta nilai kepada pengguna, tetapi Anda dapat menggunakan JavaScript atau CSS kustom untuk menyembunyikan bidang input dari pengguna akhir.

Lihat contoh respons kelanjutan.

Tanggapan Pemblokiran

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.

Sebelum mengirim token (pratinjau)

Penting

Konektor API yang digunakan dalam langkah ini sedang dalam masa pratinjau. Untuk informasi selengkapnya tentang pratinjau, lihat Ketentuan Produk untuk Layanan Online.

Konektor API pada langkah ini dipanggil ketika token akan dikeluarkan selama masuk dan pendaftaran. Konektor API untuk langkah ini dapat digunakan untuk memperkaya token dengan nilai klaim dari sumber eksternal.

Contoh permintaan dikirim ke API pada langkah ini

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

{
 "clientId": "11112222-bbbb-3333-cccc-4444dddd5555",
 "step": "PreTokenApplicationClaims",
 "ui_locales":"en-US",
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
}

Klaim yang dikirim ke API bergantung pada informasi yang ditentukan untuk pengguna.

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:

Tanggapan Lanjutan

Tanggapan Lanjutan

Respons kelanjutan menunjukkan bahwa alur pengguna harus berlanjut ke langkah berikutnya: mengeluarkan token.

Dalam respons kelanjutan, API dapat mengembalikan klaim tambahan. Klaim yang dikembalikan oleh API yang ingin Anda kembalikan dalam token harus berupa klaim bawaan atau didefinisikan sebagai atribut kustom dan harus dipilih dalam konfigurasi klaim Aplikasi dari alur pengguna.

Nilai klaim dalam token akan menjadi nilai yang dikembalikan oleh API, bukan nilai dalam direktori. Beberapa nilai klaim tidak dapat ditimpa oleh respons API. Klaim yang dapat dikembalikan oleh API sesuai dengan set yang ditemukan di bawah Atribut pengguna dengan pengecualian email.

Lihat contoh respons kelanjutan.

Nota

API hanya dipanggil selama autentikasi awal. Saat menggunakan token refresh untuk mendapatkan token akses atau ID baru secara diam-diam, token akan menyertakan nilai yang dievaluasi selama autentikasi awal.

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
}

Pengaturan	Tipe	Diperlukan	Deskripsi
versi	string	Ya	Versi API Anda.
perbuatan	string	Ya	Nilai harus `Continue`.
<builtInUserAttribute>	<tipe atribut>	Tidak.	Nilai yang dikembalikan dapat menimpa nilai yang dikumpulkan dari pengguna.
<extension_{extensions-app-id}_CustomAttribute>	<tipe atribut>	Tidak.	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 a problem with your request. You are not able to sign up at this time. Please contact your system administrator",
}

Pengaturan	Tipe	Diperlukan	Deskripsi
versi	string	Ya	Versi API Anda.
perbuatan	string	Ya	Nilai harus `ShowBlockPage`
pesanPengguna	string	Ya	Pesan yang ditampilkan kepada pengguna.

Pengalaman pengguna akhir terhadap respons pemblokiran

Contoh 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."
}

Pengaturan	Tipe	Diperlukan	Deskripsi
versi	string	Ya	Versi API Anda.
perbuatan	string	Ya	Nilai harus `ValidationError`.
kedudukan	Bilangan bulat/String	Ya	Harus bernilai `400`, atau `"400"` untuk respons KesalahanValidasi.
pesanPengguna	string	Ya	Pesan yang ditampilkan kepada pengguna.

Nota

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

Pengalaman pengguna akhir dengan respons kesalahan validasi

Contoh respons kesalahan validasi

Menyiapkan titik akhir REST API

Untuk panduan ini, Anda harus memiliki REST API yang memvalidasi apakah alamat email terdaftar di sistem back-end Anda dengan ID loyalitas. Jika terdaftar, REST API harus mengembalikan kode promosi pendaftaran, yang dapat digunakan pelanggan untuk membeli barang dalam aplikasi Anda. Jika tidak, REST API harus mengembalikan pesan kesalahan HTTP 409: "ID Loyalitas '{LOYALTY ID}' tidak terkait dengan alamat email '{email}'.".

Kode JSON berikut mengilustrasikan data yang akan dikirim Azure AD B2C ke titik akhir REST API Anda.

{
    "email": "User email address",
    "language": "Current UI language",
    "loyaltyId": "User loyalty ID"
}

Setelah REST API Memvalidasi data, REST API harus mengembalikan HTTP 200 (Ok), dengan data JSON berikut:

{
    "promoCode": "24534"
}

Jika validasi gagal, REST API harus mengembalikan HTTP 409 (Konflik), dengan userMessage elemen JSON. IEF mengharapkan klaim userMessage yang dikembalikan oleh REST API. Klaim ini akan disajikan sebagai string kepada pengguna jika validasi gagal.

{
    "version": "1.0.1",
    "status": 409,
    "userMessage": "LoyaltyId ID '1234' is not associated with 'david@contoso.com' email address."
}

Penyiapan titik akhir REST API berada di luar cakupan artikel ini. Kami telah membuat sampel Azure Functions . Anda dapat mengakses kode fungsi Azure lengkap di GitHub.

Menetapkan definisi klaim

Klaim menyediakan penyimpanan data sementara selama eksekusi kebijakan Azure AD B2C. Anda dapat mendeklarasikan klaim dalam bagian skema klaim .

Buka file ekstensi kebijakan Anda. Contohnya, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
Cari elemen BuildingBlocks . Jika elemen tidak ada, tambahkan elemen tersebut.
Temukan elemen ClaimsSchema . Jika elemen tidak ada, tambahkan elemen tersebut.
Tambahkan klaim berikut ke elemen ClaimsSchema .

<ClaimType Id="loyaltyId">
  <DisplayName>Your loyalty ID</DisplayName>
  <DataType>string</DataType>
  <UserInputType>TextBox</UserInputType>
</ClaimType>
<ClaimType Id="promoCode">
  <DisplayName>Your promo code</DisplayName>
  <DataType>string</DataType>
  <UserInputType>Paragraph</UserInputType>
</ClaimType>
  <ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

Menambahkan profil teknis RESTful API

Profil teknis RESTful menyediakan dukungan untuk berinteraksi dengan layanan RESTful Anda sendiri. Azure AD B2C mengirim data ke layanan RESTful dalam InputClaims sekumpulan data dan menerima data kembali dalam sekumpulan data OutputClaims. Temukan elemen ClaimsProviders dan tambahkan penyedia klaim baru sebagai berikut:

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-ValidateProfile">
      <DisplayName>Check loyaltyId Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/ValidateProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="loyaltyId" />
        <InputClaim ClaimTypeReferenceId="email" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Dalam contoh ini, userLanguage akan dikirim ke layanan REST seperti lang dalam payload JSON. Nilai userLanguage klaim berisi ID bahasa pengguna saat ini. Untuk informasi selengkapnya, lihat penyelesai klaim.

Mengonfigurasi profil teknis RESTful API

Setelah Anda menyebarkan REST API, atur metadata REST-ValidateProfile profil teknis untuk mencerminkan REST API Anda sendiri, termasuk:

Url Layanan. Atur URL titik akhir REST API.
KirimKlaimMasuk. Tentukan bagaimana klaim input dikirim ke penyedia klaim RESTful.
AuthenticationType. Atur jenis autentikasi yang dilakukan oleh penyedia klaim RESTful.
IzinSecureAuthInProduction. Di lingkungan produksi, pastikan untuk mengatur metadata ini ke true

Lihat metadata profil teknis RESTful untuk konfigurasi lainnya.

Komentar di atas AuthenticationType dan AllowInsecureAuthInProduction menentukan perubahan yang harus Anda buat saat pindah ke lingkungan produksi. Untuk mempelajari cara mengamankan API RESTful Anda untuk produksi, lihat API Secure RESTful.

Memvalidasi input pengguna

Untuk mendapatkan nomor loyalitas pengguna selama pendaftaran, Anda harus mengizinkan pengguna memasukkan data ini di layar. Tambahkan klaim output loyaltyId ke halaman pendaftaran dengan menambahkannya ke elemen profil OutputClaims teknis pendaftaran yang ada. Tentukan seluruh daftar klaim output untuk mengontrol urutan klaim yang disajikan di layar.

Tambahkan referensi profil teknis validasi ke dalam profil teknis pendaftaran, yang memanggil REST-ValidateProfile. Profil teknis validasi baru akan ditambahkan ke bagian atas koleksi <ValidationTechnicalProfiles> yang ditentukan dalam kebijakan dasar. Perilaku ini berarti bahwa hanya setelah validasi berhasil, Azure AD B2C melanjutkan untuk membuat akun di direktori.

Temukan elemen ClaimsProviders . Tambahkan penyedia klaim baru sebagai berikut:

<ClaimsProvider>
  <DisplayName>Local Account</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="LocalAccountSignUpWithLogonEmail">
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="Verified.Email" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="newPassword" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="reenterPassword" Required="true"/>
        <OutputClaim ClaimTypeReferenceId="displayName"/>
        <OutputClaim ClaimTypeReferenceId="givenName"/>
        <OutputClaim ClaimTypeReferenceId="surName"/>
        <!-- Required to present the text box to collect the data from the user -->
        <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
        <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
        to subsequent orchestration steps and token issuance-->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile" />
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>
<ClaimsProvider>
  <DisplayName>Self Asserted</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="SelfAsserted-Social">
      <InputClaims>
        <InputClaim ClaimTypeReferenceId="email" />
      </InputClaims>
        <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="displayName"/>
        <OutputClaim ClaimTypeReferenceId="givenName"/>
        <OutputClaim ClaimTypeReferenceId="surname"/>
        <!-- Required to present the text box to collect the data from the user -->
        <OutputClaim ClaimTypeReferenceId="loyaltyId"/>
        <!-- Required to pass the promoCode returned from "REST-ValidateProfile" 
        to subsequent orchestration steps and token issuance-->
        <OutputClaim ClaimTypeReferenceId="promoCode" />
      </OutputClaims>
      <ValidationTechnicalProfiles>
        <ValidationTechnicalProfile ReferenceId="REST-ValidateProfile"/>
      </ValidationTechnicalProfiles>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Menyertakan klaim dalam token

Untuk mengembalikan klaim kode promo kembali ke aplikasi pihak yang mengandalkan, tambahkan klaim output ke SocialAndLocalAccounts/SignUpOrSignIn.xml file. Klaim keluaran akan memungkinkan klaim ditambahkan ke dalam token setelah rangkaian perjalanan pengguna yang berhasil, dan akan dikirim ke aplikasi. Ubah elemen profil teknis dalam bagian pihak yang mengandalkan untuk menambahkan promoCode sebagai klaim output.

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="promoCode" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Menguji kebijakan khusus

Masuk ke portal Azure.
Jika Anda memiliki akses ke beberapa penyewa, pilih ikon Pengaturan di menu atas untuk beralih ke penyewa Microsoft Entra ID Anda dari menu Direktori + langganan.
Pilih Semua layanan di sudut kiri atas portal Microsoft Azure, lalu cari dan pilih Pendaftaran aplikasi.
Pilih Kerangka Kerja Pengalaman Identitas.
Pilih Unggah Kebijakan Kustom, lalu unggah file kebijakan yang Anda ubah: TrustFrameworkExtensions.xml, dan SignUpOrSignin.xml.
Pilih kebijakan pendaftaran atau masuk yang Anda unggah, dan klik tombol Jalankan sekarang .
Anda harus dapat mendaftar menggunakan alamat email.
Klik tautan Daftar sekarang .
Di ID loyalitas Anda, ketik 1234, dan klik Lanjutkan. Pada titik ini, Anda akan mendapatkan pesan kesalahan validasi.
Ubah ke nilai lain dan klik Lanjutkan.
Token yang dikirim kembali ke aplikasi Anda menyertakan klaim promoCode.

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584295703,
  "nbf": 1584292103,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "22223333-cccc-4444-dddd-5555eeee6666",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584292103,
  "auth_time": 1584292103,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "promoCode": "84362"
  ...
}

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 menjadi dasar kegiatannya.
API Anda menerapkan metode autentikasi yang diuraikan dalam mengamankan konektor API Anda.
API Anda merespons secepat mungkin untuk memastikan pengalaman pengguna yang lancar.
- Azure AD B2C akan menunggu maksimal 10 detik untuk menerima respons. Jika tidak ada yang diterima, sistem akan melakukan satu percobaan tambahan (coba lagi) saat memanggil API Anda.
- Jika menggunakan fungsi tanpa server atau layanan web yang dapat diskalakan, gunakan paket hosting yang membuat API tetap "aktif" atau "hangat" saat produksi. Untuk Azure Functions, disarankan untuk menggunakan minimal paket Premium dalam produksi.
Pastikan API Anda dalam ketersediaan yang tinggi.
Pantau dan optimalkan kinerja API, database, atau dependensi API hilir lainnya.

Penting

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

Gunakan pencatatan

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.

Selain itu, Azure AD B2C mencatat metadata tentang transaksi API yang terjadi selama autentikasi pengguna melalui alur pengguna. Untuk menemukan hal-hal ini:

Buka Azure AD B2C.
Di bawah Aktivitas, pilih Log audit.
Filter tampilan daftar: Untuk Tanggal, pilih interval waktu yang Anda inginkan, dan untuk Aktivitas, pilih API dipanggil sebagai bagian dari alur pengguna.
Memeriksa log individual. Setiap baris mewakili konektor API yang mencoba dipanggil selama alur pengguna. Jika panggilan API gagal dan upaya ulang dilakukan, panggilan tetap diwakili sebagai satu baris. numberOfAttempts menunjukkan berapa kali API Anda dipanggil. Nilai ini bisa berupa 1 atau 2. Informasi lain tentang panggilan API dirinci dalam log.

Contoh transaksi konektor API selama autentikasi pengguna

Menggunakan fungsi cloud tanpa server

Fungsi cloud tanpa server, seperti pemicu HTTP di Azure Functions, menyediakan cara sederhana, sangat tersedia, berkinerja tinggi untuk membuat titik akhir API untuk digunakan sebagai konektor API.

Praktik terbaik

Pastikan bahwa:

API Anda secara eksplisit memeriksa nilai null dari klaim yang diterima yang menjadi dasar kegiatannya.
API Anda menerapkan metode autentikasi yang diuraikan dalam mengamankan konektor API Anda.
API Anda merespons secepat mungkin untuk memastikan pengalaman pengguna yang lancar.
- Jika menggunakan fungsi tanpa server atau layanan web yang dapat diskalakan, gunakan paket hosting yang membuat API tetap "aktif" atau "hangat" saat produksi. Untuk Azure Functions, disarankan untuk menggunakan minimal paket Premium
Pastikan API Anda dalam ketersediaan yang tinggi.
Pantau dan optimalkan kinerja API, database, atau dependensi API hilir lainnya.

Penting

Gunakan pencatatan

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 selanjutnya

Mulai dengan sampel kami.
Mengamankan Konektor API Anda

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-04-18

Bagikan melalui

Menambahkan konektor API ke alur pengguna pendaftaran

Prasyarat

Membuat konektor API

Permintaan dikirim ke API Anda

Mengaktifkan konektor API dalam alur pengguna

Setelah mengintegrasikan dengan penyedia identitas saat mendaftar

Contoh permintaan dikirim ke API pada langkah ini

Jenis respons yang diharapkan dari API web pada langkah ini

Tanggapan Lanjutan

Tanggapan Pemblokiran

Sebelum membuat pengguna

Contoh permintaan dikirim ke API pada langkah ini

Jenis respons yang diharapkan dari API web pada langkah ini

Tanggapan Lanjutan

Tanggapan Pemblokiran

Respons kesalahan validasi

Sebelum mengirim token (pratinjau)

Contoh permintaan dikirim ke API pada langkah ini

Jenis respons yang diharapkan dari API web pada langkah ini

Tanggapan Lanjutan

Contoh respons

Contoh respons kelanjutan

Contoh respons pemblokiran

Contoh respons kesalahan validasi

Menyiapkan titik akhir REST API

Menetapkan definisi klaim

Menambahkan profil teknis RESTful API

Mengonfigurasi profil teknis RESTful API

Memvalidasi input pengguna

Menyertakan klaim dalam token

Menguji kebijakan khusus

Praktik terbaik dan cara memecahkan masalah

Menggunakan fungsi cloud tanpa server

Praktik terbaik

Gunakan pencatatan

Menggunakan fungsi cloud tanpa server

Praktik terbaik

Gunakan pencatatan

Langkah selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: