Bagikan melalui

Menambahkan konektor API ke alur pengguna pendaftaran

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

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. Di akhir panduan ini, Anda dapat membuat alur pengguna Azure AD B2C yang berinteraksi dengan layanan REST API untuk memodifikasi pengalaman pendaftaran anda.

Anda dapat menciptakan titik akhir API menggunakan salah satu sampel dari 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. Terakhir, kode promosi akan dimasukkan ke dalam klaim token untuk dipakai aplikasi.

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

Prasyarat

Membuat konektor API

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

  1. Masuk ke portal Azure.

  2. Di bagian Layanan Azure, pilih Azure AD B2C.

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

    Screenshot of basic configuration for an API connector

  4. Berikan nama tampilan untuk panggilan tersebut. Misalnya, Memvalidasi informasi pengguna.

  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.

    Screenshot of authentication configuration for an API connector

  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": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "11111111-0000-0000-0000-000000000000",
 "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":"93fd07aa-333c-409d-955d-96008fd08dd9",
 "ui_locales":"en-US"
}

Hanya properti pengguna dan atribut khusus yang tercantum dalam pengalaman Azure AD B2C>Atribut pengguna yang tersedia untuk dikirim dalam permintaan.

Atribut kustom ada dalam format extension_<extensions-app-id>_CustomAttribute di dalam 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 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 aliran pengguna yang untuknya konektor API dipanggil. Nilai meliputi:
    • PostFederationSignup - sesuai dengan "Setelah bergabung dengan IdP saat mendaftar"
    • PostAttributeCollection - sesuai dengan "Sebelum membuat pengguna"
    • PreTokenIssuance - sesuai dengan "Sebelum mengirim token (pratinjau)". Pelajari selengkapnya tentang langkah ini
  • ID Klien ('client_id') - Adalah nilai appId aplikasi yang pengguna akhir autentikasikan di alur pengguna. Ini bukanappId aplikasi sumber daya 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.

  1. Masuk ke portal Azure.

  2. Di bagian Layanan Azure, pilih Azure AD B2C.

  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
    • Sebelum mengirim token (pratinjau)

    Selecting an API connector for a step in the user flow

  5. Pilih Simpan.

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

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 ke 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 pasti yang dikirim ke API tergantung pada informasi mana yang disediakan oleh IdP. '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 terlebih dahulu bidang input di 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.

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":"93fd07aa-333c-409d-955d-96008fd08dd9",
 "ui_locales":"en-US"
}

Klaim yang dikirim ke API bergantung pada informasi yang dikumpulkan dari pengguna atau disediakan oleh IdP.

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:

  • Mengesampingkan nilai apa pun yang telah disediakan oleh pengguna di halaman pengumpulan atribut.

Untuk menulis klaim ke direktori pada pendaftaran yang tidak boleh dikumpulkan dari pengguna, Anda masih harus memilih klaim di bawah tribut Pengguna dari aliran pengguna, yang secara default akan meminta nilai pengguna, tetapi Anda dapat menggunakan JavaScript atau CSS khusus untuk menyembunyikan bidang input dari pengguna akhir.

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 koleksi 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 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 mendaftar. 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": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "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 tergantung 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:

  • Respons kelanjutan

Respons kelanjutan

Respons kelanjutan menunjukkan bahwa alur pengguna harus berlanjut ke langkah berikutnya: menerbitkan 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 khusus dan harus dipilih dalam konfigurasi Klaim aplikasi dari aliran 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.

Catatan

API hanya dipanggil selama autentikasi awal. Saat menggunakan token refresh untuk diam-diam mendapatkan akses baru atau token ID, 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
}
Parameter Jenis Wajib Deskripsi
versi String Ya Versi API Anda.
tindakan String Ya Nilai harus Continue.
<builtInUserAttribute> <attribute-type> Tidak Nilai yang dikembalikan dapat menimpa nilai yang dikumpulkan dari pengguna.
<extension_{extensions-app-id}_CustomAttribute> <attribute-type> Tidak Klaim tidak perlu berisi _<extensions-app-id>_, isi tersebut bersifat 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",
}
Parameter Jenis 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

Example of a blocking response

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

Example of a validation-error response

Menyiapkan titik akhir REST API

Untuk panduan ini, Anda harus memiliki REST API yang memvalidasi apakah alamat surel 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 '{email}' alamat surel.".

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 Anda memvalidasi data, ia harus mengembalikan HTTP 200 (Ok), dengan data JSON berikut:

{
    "promoCode": "24534"
}

Jika validasi gagal, REST API harus mengembalikan HTTP 409 (Konflik), dengan elemen JSON userMessage. IEF mengharapkan klaim userMessage bahwa REST API kembali. 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.

Tentukan klaim

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

  1. Buka file ekstensi kebijakan Anda. Contohnya, SocialAndLocalAccounts/TrustFrameworkExtensions.xml.
  2. Cari elemen BuildingBlocks. Jika elemen tersebut tidak ada, tambahkan.
  3. Temukan elemen ClaimsSchema. Jika elemen tersebut tidak ada, tambahkan.
  4. 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 bersinggungan dengan layanan RESTful Anda sendiri. Azure AD B2C mengirim data ke layanan RESTful dalam InputClaims koleksi dan menerima data kembali dalam OutputClaims koleksi. Temukan elemen ClaimsProviders dan tambahkan penyedia klaim baru 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 dalam lang payload JSON. Nilai klaim userLanguage berisi ID bahasa komputer pengguna saat ini. Untuk informasi selengkapnya, lihat penyelesai klaim.

Mengonfigurasi profil teknis RESTful API

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

  • ServiceUrl. Mengatur URL titik akhir REST API.
  • SendClaimsIn. Menentukan bagaimana klaim input dikirim ke penyedia klaim RESTful.
  • AuthenticationType. Mengatur jenis autentikasi yang dilakukan oleh penyedia klaim RESTful.
  • AllowInsecureAuthInProduction. Di lingkungan produksi, pastikan untuk menetapkan metadata ini ke true

Lihat metadata profil teknis RESTful untuk konfigurasi lainnya.

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

Memvalidasi input pengguna

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

Tambahkan referensi profil teknis validasi ke 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 Azure AD B2C beralih untuk membuat akun di direktori hanya setelah validasi berhasil.

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

Sertakan klaim dalam token

Untuk mengembalikan klaim kode kembali ke aplikasi pihak yang mengandalkan, tambahkan klaim output ke file SocialAndLocalAccounts/SignUpOrSignIn.xml. Klaim output akan mengizinkan klaim ditambahkan ke dalam token setelah 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 kustom

  1. Masuk ke portal Azure.
  2. Jika Anda memiliki akses ke beberapa penyewa, pilih ikon Pengaturan di menu atas untuk beralih ke penyewa ID Microsoft Entra Anda dari menu Direktori + langganan.
  3. Pilih Semua layanan di sudut kiri atas portal Microsoft Azure, lalu cari dan pilih Pendaftaran aplikasi.
  4. Pilih IEF.
  5. Pilih Unggah Kebijakan Kustom, lalu unggah file kebijakan yang Anda ubah: TrustFrameworkExtensions.xml, dan SignUpOrSignin.xml.
  6. Pilih kebijakan pendaftaran atau masuk yang Anda unggah, dan klik tombol Jalankan sekarang.
  7. Anda harus dapat mendaftar dengan menggunakan alamat surel.
  8. Klik tautan Daftar sekarang.
  9. Di ID loyalitas Anda, ketik 1234, kemudian klik Lanjutkan. Pada titik ini, Anda seharusnya mendapatkan pesan kesalahan validasi.
  10. Ubah ke nilai lain dan klik Lanjutkan.
  11. Token yang dikirim kembali ke aplikasi Anda termasuk klaim promoCode.
{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584295703,
  "nbf": 1584292103,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/f06c2fe8-709f-4030-85dc-38a4bfd9e82d/v2.0/",
  "aud": "e1d2612f-c2bc-4599-8e7b-d874eaca1ee1",
  "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 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.
    • Azure AD B2C akan menunggu maksimal 20 detik untuk menerima respons. Jika tidak ada yang diterima, AAD akan membuat satu upaya lagi (coba ulang) untuk 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, disarankan untuk menggunakan setidaknya 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 lebih lanjut, lihat Persyaratan Azure AD B2C 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.

Selain itu, Azure AD B2C mencatat metadata tentang transaksi API yang terjadi selama autentikasi pengguna melalui aliran pengguna. Untuk menemukannya:

  1. Pergi ke Azure AD B2C.
  2. Di bawah Aktivitas, pilih Log audit.
  3. Filter tampilan daftar: Untuk Tanggal, pilih interval waktu yang Anda inginkan, dan untuk Aktivitas, pilih API disebut sebagai bagian dari alur pengguna.
  4. Memeriksa log individu. Setiap baris mewakili konektor API yang mencoba dipanggil selama aliran pengguna. Jika panggilan API gagal dan percobaan ulang terjadi, maka masih direpresentasikan sebagai baris tunggal. numberOfAttempts menunjukkan berapa kali API Anda dipanggil. Nilai ini dapat berupa 1 atau 2. Informasi lain tentang panggilan API dirinci dalam log.

Example of an API connector transaction during user authentication

Menggunakan fungsi cloud tanpa server

Fungsi cloud tanpa server, seperti pemicu HTTP di Azure Functions, menyediakan cara yang 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 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.
    • 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, disarankan untuk menggunakan setidaknya Paket premium
  • 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 lebih lanjut, lihat Persyaratan Azure AD B2C 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