Bagikan melalui

Tentukan profil teknis RESTful dalam kebijakan kustom Azure Active Directory B2C

  • Artikel

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.

Azure Active Directory B2C (Azure AD B2C) menyediakan dukungan untuk mengintegrasikan layanan RESTful Anda sendiri. Azure AD B2C mengirim data ke layanan RESTful dalam pengumpulan klaim input dan menerima data kembali dalam pengumpulan klaim output. Untuk informasi selengkapnya, lihat Mengintegrasikan pertukaran klaim REST API di kebijakan kustom Azure AD B2C Anda.

Protokol

Atribut Nama dari elemen Protokol perlu diatur ke Proprietary. Atribut handler harus berisi nama yang sepenuhnya memenuhi syarat dari perakitan handler protokol yang digunakan oleh Azure AD B2C: Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.

Contoh berikut menunjukkan profil teknis RESTful:

<TechnicalProfile Id="REST-UserMembershipValidator">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...

Klaim input

Elemen InputClaims berisi daftar klaim untuk dikirim ke REST API. Anda juga dapat memetakan nama klaim Anda ke nama yang ditentukan dalam REST API. Contoh berikut menunjukkan pemetaan antara kebijakan Anda dan REST API. Klaim givenName dikirim ke REST API sebagai firstName, sedangkan surname dikirim sebagai lastName. Klaim email diatur apa adanya.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="email" />
  <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName" />
  <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName" />
</InputClaims>

Elemen InputClaimsTransformations mungkin berisi kumpulan elemen InputClaimsTransformation yang digunakan untuk mengubah klaim input atau membuat yang baru sebelum mengirim ke REST API.

Kirim muatan JSON

Profil teknis REST API memungkinkan Anda untuk mengirim muatan JSON yang kompleks ke titik akhir.

Untuk mengirim muatan JSON yang kompleks:

  1. Bangun payload JSON Anda dengan transformasi klaim GenerateJson.
  2. Di profil teknis REST API:
    1. Tambahkan transformasi klaim input dengan referensi ke transformasi klaim GenerateJson.
    2. Setel opsi metadata SendClaimsIn ke body
    3. Setel opsi metadata ClaimUsedForRequestPayload ke nama klaim yang berisi muatan JSON.
    4. Dalam klaim input, tambahkan referensi ke klaim input yang berisi muatan JSON.

Contoh berikut TechnicalProfile mengirimkan email verifikasi dengan menggunakan layanan email pihak ketiga (dalam hal ini, SendGrid).

<TechnicalProfile Id="SendGrid">
  <DisplayName>Use SendGrid's email API to send the code to the user</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://api.sendgrid.com/v3/mail/send</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="ClaimUsedForRequestPayload">sendGridReqBody</Item>
    <Item Key="DefaultUserMessageIfRequestFailed">Cannot process your request right now, please try again later.</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_SendGridApiKey" />
  </CryptographicKeys>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="GenerateSendGridRequestBody" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="sendGridReqBody" />
  </InputClaims>
</TechnicalProfile>

Klaim output

Elemen OutputClaims 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 REST API, selama Anda mengatur atribut DefaultValue.

Elemen OutputClaimsTransformations mungkin berisi kumpulan elemen OutputClaimsTransformation yang digunakan untuk memodifikasi klaim output atau menghasilkan yang baru.

Contoh berikut menunjukkan klaim yang dikembalikan oleh REST API:

  • Klaim MembershipId yang dipetakan ke nama klaim loyaltyNumber.

Profil teknis juga menampilkan klaim, yang tidak ditampilkan oleh IdP:

  • LoyalitasNumberIsNew mengklaim yang memiliki nilai default yang ditetapkan ke true.
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

Metadata

Atribut Wajib Deskripsi
ServiceUrl Ya URL titik akhir REST API.
AuthenticationType Ya Jenis autentikasi yang dilakukan oleh penyedia klaim RESTful. Nilai yang mungkin: None, Basic, Bearer, ClientCertificate, atau ApiKeyHeader.
  • Nilai None menunjukkan bahwa REST API bersifat anonim.
  • Nilai Basic menunjukkan bahwa REST API diamankan dengan autentikasi dasar HTTP. Hanya pengguna terverifikasi, termasuk Azure AD B2C, yang dapat mengakses API Anda.
  • Nilai ClientCertificate (direkomendasikan) menunjukkan bahwa REST API membatasi akses dengan menggunakan autentikasi sertifikat klien. Hanya layanan yang memiliki sertifikat yang sesuai, misalnya Azure AD B2C, yang dapat mengakses API Anda.
  • Nilai Bearer menunjukkan bahwa REST API membatasi akses menggunakan token pembawa OAuth2 klien.
  • Nilai ApiKeyHeader menunjukkan bahwa REST API diamankan dengan header HTTP kunci API, seperti x-functions-key.
AllowInsecureAuthInProduction No Menunjukkan apakah AuthenticationType bisa disetel ke none dalam lingkungan produksi (DeploymentMode dari TrustFrameworkPolicy disetel ke Production, atau tidak ditentukan). Nilai yang mungkin: benar, atau salah (default).
SendClaimsIn No Menentukan bagaimana klaim input dikirim ke penyedia klaim RESTful. Nilai yang mungkin: Body (default), Form, Header, Url atau QueryString.
Nilai Body adalah klaim input yang dikirim dalam badan permintaan dalam format JSON.
Nilai Form adalah klaim input yang dikirim dalam badan permintaan dalam format nilai kunci yang dipisahkan ampersand '&'.
Nilai Header adalah klaim input yang dikirim di header permintaan.
Nilai Url adalah klaim input yang dikirim dalam URL, misalnya, https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}. Bagian nama host URL tidak boleh berisi klaim.
Nilai QueryString adalah klaim input yang dikirim dalam string kueri permintaan.
Kata kerja HTTP yang dipanggil oleh masing-masing adalah sebagai berikut:
  • Body: POST
  • Form: POST
  • Header: GET
  • Url: GET
  • QueryString: GET
ClaimsFormat No Saat ini tidak digunakan, dapat diabaikan.
ClaimUsedForRequestPayload No Nama klaim string yang berisi muatan yang akan dikirim ke REST API.
DebugMode No Menjalankan profil teknis dalam mode debug. Nilai yang mungkin: true, atau false (default). Dalam mode debug, REST API dapat mengembalikan informasi lebih lanjut. Lihat bagian Pesan kesalahan yang berulang.
IncludeClaimResolvingInClaimsHandling No Untuk klaim input dan output, menentukan apakah resolusi klaim disertakan dalam profil teknis atau tidak. Nilai yang mungkin: true, atau false (default). Jika Anda ingin menggunakan penyelesai klaim di profil teknis, atur ini ke true.
ResolveJsonPathsInJsonTokens No Menunjukkan apakah profil teknis menyelesaikan jalur JSON. Nilai yang mungkin: true, atau false (default). Gunakan metadata ini untuk membaca data dari elemen JSON berlapis. Dalam OutputClaim, atur PartnerClaimType ke elemen jalur JSON yang ingin Anda keluarkan. Misalnya: firstName.localized, atau data[0].to[0].email.
UseClaimAsBearerToken No Nama klaim yang berisi token pembawa.

Penanganan kesalahan

Metadata berikut dapat digunakan untuk mengonfigurasi pesan kesalahan yang ditampilkan pada kegagalan REST API. Pesan kesalahan dapat dilokalisasi.

Atribut Wajib Deskripsi
DefaultUserMessageJikaRequestFailed No Pesan kesalahan default yang dikustomisasi untuk semua pengecualian REST API.
UserMessageIfCircuitOpen No Pesan kesalahan saat REST API tidak dapat dijangkau. Jika tidak ditentukan, DefaultUserMessageIfRequestFailed akan dikembalikan.
UserMessageIfDnsResolutionFailed No Pesan kesalahan untuk pengecualian resolusi DNS. Jika tidak ditentukan, DefaultUserMessageIfRequestFailed akan dikembalikan.
UserMessageIfRequestTimeout No Pesan kesalahan ketika koneksi kehabisan waktu. Jika tidak ditentukan, DefaultUserMessageIfRequestFailed akan dikembalikan.

Kunci kriptografi

Jika jenis autentikasi diatur ke None, elemen CryptographicKeys tidak digunakan.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
</TechnicalProfile>

Jika jenis autentikasi diatur ke Basic, elemen CryptographicKeys berisi atribut berikut ini:

Atribut Wajib Deskripsi
BasicAuthenticationUsername Ya Nama pengguna yang digunakan untuk mengautentikasi.
BasicAuthenticationPassword Ya Kata sandi yang digunakan untuk mengautentikasi.

Contoh berikut menunjukkan profil teknis dengan autentikasi dasar:

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Basic</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_B2cRestClientId" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_B2cRestClientSecret" />
  </CryptographicKeys>
</TechnicalProfile>

Jika jenis autentikasi diatur ke ClientCertificate, elemen CryptographicKeys berisi atribut berikut ini:

Atribut Wajib Deskripsi
ClientCertificate Ya Sertifikat X509 (set kunci RSA) yang digunakan untuk mengautentikasi. 
<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ClientCertificate</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_B2cRestClientCertificate" />
  </CryptographicKeys>
</TechnicalProfile>

Jika jenis autentikasi diatur ke Bearer, elemen CryptographicKeys berisi atribut berikut ini:

Atribut Wajib Deskripsi
BearerAuthenticationToken No Token Pembawa OAuth 2.0. 
<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_B2cRestClientAccessToken" />
  </CryptographicKeys>
</TechnicalProfile>

Jika jenis autentikasi diatur ke ApiKeyHeader, elemen CryptographicKeys berisi atribut berikut ini:

Atribut Wajib Deskripsi
Nama header HTTP, seperti x-functions-key, atau x-api-key. Ya Kunci yang digunakan untuk mengautentikasi.

Catatan

Saat ini, Azure AD B2C hanya mendukung satu header HTTP untuk autentikasi. Jika panggilan RESTful Anda memerlukan beberapa header, seperti ID klien dan rahasia klien, Anda harus memproksi permintaan dengan cara tertentu.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</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-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ApiKeyHeader</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
  </CryptographicKeys>
</TechnicalProfile>

Mengembalikan pesan kesalahan validasi

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 4xx, seperti, 400 (permintaan buruk), atau kode status respons 409 (konflik). Isi respons berisi pesan kesalahan yang diformat di JSON:

{
  "version": "1.0.0",
  "status": 409,
  "code": "API12345",
  "requestId": "50f0bd91-2ff4-4b8f-828f-00f170519ddb",
  "userMessage": "Message for the user",
  "developerMessage": "Verbose description of problem and how to fix it.",
  "moreInfo": "https://restapi/error/API12345/moreinfo"
}
Atribut Wajib Deskripsi
versi Ya Versi REST API Anda. Misalnya: 1.0.1
status Ya Nomor seperti kode respons HTTP, dan harus 409. Layanan REST Anda dapat mengembalikan kode status HTTP 4XX, tetapi nilai yang status diajukan dalam isi respons berformat JSON harus 409.
code No Kode kesalahan dari penyedia titik akhir RESTful, yang ditampilkan saat DebugMode diaktifkan.
requestId No Pengidentifikasi permintaan dari penyedia endpoint RESTful, yang ditampilkan saat DebugMode diaktifkan.
userMessage Ya Pesan kesalahan yang diperlihatkan kepada pengguna.
developerMessage No Deskripsi verbose tentang masalah dan cara memperbaikinya, yang ditampilkan saat DebugMode diaktifkan.
moreInfo No URI yang menunjuk ke informasi tambahan, yang ditampilkan saat DebugMode diaktifkan.

Contoh berikut memperlihatkan kelas C# yang menampilkan pesan kesalahan:

public class ResponseContent
{
  public string Version { get; set; }
  public int Status { get; set; }
  public string Code { get; set; }
  public string UserMessage { get; set; }
  public string DeveloperMessage { get; set; }
  public string RequestId { get; set; }
  public string MoreInfo { get; set; }
}

Langkah berikutnya

Lihat artikel berikut ini untuk contoh penggunaan profil teknis RESTful: