Menentukan profil teknis penyedia identitas SAML di dalam sebuah kebijakan kustom di Azure Active Directory B2C

Artikel
01/11/2024

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 penyedia identitas SAML 2.0. Artikel ini menjelaskan secara spesifik profil teknis untuk berinteraksi dengan penyedia klaim yang mendukung protokol standar ini. Dengan profil teknis SAML Anda dapat menggabungkan dengan penyedia identitas berbasis SAML, seperti ADFS dan Salesforce. Penggabungan ini memungkinkan pengguna Anda untuk masuk dengan identitas sosial atau perusahaan yang sudah ada.

Pertukaran metadata

Metadata adalah informasi yang digunakan dalam protokol SAML untuk mengekspos konfigurasi pihak SAML, seperti sebuah penyedia layanan atau penyedia identitas (IdP). Metadata mendefinisikan lokasi layanan, seperti rincian masuk dan keluar, sertifikat, metode masuk, dan lainnya. IdP menggunakan metadata untuk mengetahui cara berkomunikasi dengan Azure AD B2C. Metadata dikonfigurasi dalam format XML dan dapat ditandatangani dengan tanda tangan digital sehingga pihak lain dapat memvalidasi integritas metadatanya. Ketika Azure AD B2C bergabung dengan IdP SAML, ia bertindak sebagai penyedia layanan yang memulai permintaan SAML dan menunggu sebuah respons SAML. Dan, dalam beberapa kasus, menerima autentikasi SAML yang tidak diminta, yang juga dikenal sebagai IdP yang dimulai.

Metadata dapat dikonfigurasi di kedua belah pihak sebagai "Metadata Statis" atau "Metadata Dinamis". Dalam mode statis, Anda menyalin seluruh metadata dari satu pihak dan mengaturnya di pihak lain. Dalam mode dinamis, Anda mengatur URL ke metadata saat pihak lain membaca konfigurasi secara dinamis. Prinsipnya sama, Anda mengatur metadata profil teknis Azure AD B2C di IdP Anda dan mengatur metadata IdP di Azure AD B2C.

Setiap IdP SAML memiliki langkah berbeda untuk mengekspos dan mengatur penyedia layanan, dalam hal ini Azure AD B2C, dan mengatur metadata Azure AD B2C di IdP. Lihat dokumentasi IdP Anda untuk panduan tentang cara melakukannya.

Contoh berikut ini memperlihatkan alamat URL ke metadata SAML dari profil teknis Azure AD B2C:

https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com/your-policy/samlp/metadata?idptp=your-technical-profile

Ganti nilai berikut:

your-tenant-name dengan nama penyewa Anda, seperti fabrikam.b2clogin.com.
your-policy dengan nama kebijakan Anda. Gunakan kebijakan tempat Anda mengonfigurasi profil teknis penyedia SAML, atau kebijakan yang mewarisi kebijakan tersebut.
your-technical-profile dengan nama profil teknis IdP SAML Anda.

Pertukaran sertifikat penandatanganan digital

Untuk membangun kepercayaan antara Azure AD B2C dan IdP SAML, Anda harus memberikan sertifikat X509 yang valid dengan kunci privat. Anda mengunggah sertifikat dengan kunci privat (file.pfx) ke penyimpanan kunci kebijakan Azure AD B2C. Azure AD B2C menandatangani permintaan masuk SAML secara digital menggunakan sertifikat yang Anda berikan.

Sertifikatnya digunakan dengan cara berikut:

Azure AD B2C menghasilkan dan menandatangani permintaan SAML, menggunakan kunci privat Azure AD B2C dari sertifikatnya. Permintaan SAML dikirim ke IdP, yang memvalidasi permintaan menggunakan kunci umum Azure AD B2C sertifikatnya. Sertifikat publik Azure AD B2C dapat diakses melalui metadata profil teknis. Atau, Anda dapat mengunggah file .cer secara manual ke IdP SAML Anda.
IdP menandatangani data yang dikirim ke Azure AD B2C menggunakan kunci privat IdP sertifikatnya. Azure AD B2C memvalidasi datanya menggunakan sertifikat publik IdP. Setiap IdP memiliki langkah berbeda untuk penyiapan. Lihat dokumentasi IdP Anda untuk panduan tentang cara melakukannya. Di Azure AD B2C, kebijakan Anda memerlukan akses ke kunci umum sertifikat menggunakan metadata IdP.

Sertifikat yang ditandatangani sendiri dapat diterima untuk sebagian besar skenario. Untuk lingkungan produksi, sebaiknya menggunakan sertifikat X509 yang dikeluarkan oleh otoritas sertifikat. Selain itu, seperti yang dijelaskan nantinya dalam dokumen ini, untuk lingkungan non-produksi, Anda dapat menonaktifkan penandatanganan SAML di kedua sisinya.

Diagram berikut ini memperlihatkan pertukaran metadata dan sertifikat:

Enkripsi digital

Untuk mengenkripsi pernyataan respons SAML, IdP selalu menggunakan kunci umum sertifikat enkripsi di profil teknis Azure AD B2C. Ketika Azure AD B2C perlu mendekripsi data, ia akan menggunakan bagian pribadi sertifikat enkripsi.

Untuk mengenkripsi pernyataan respons SAML:

Unggah sertifikat X509 yang valid dengan kunci privat (file .pfx) ke penyimpanan kunci kebijakan Azure AD B2C.
Tambahkan elemen CryptographicKey dengan pengidentifikasi SamlAssertionDecryption ke profil teknis CryptographicKeys pada bagian koleksinya. Atur StorageReferenceId ke nama kunci kebijakan yang telah Anda buat di langkah 1.
Atur metadata profil teknis WantsEncryptedAssertions ke true.
Perbarui IdP dengan metadata profil teknis Azure AD B2C yang baru. Anda akan melihat KeyDescriptor dengan properti gunakan diatur ke encryption yang berisi kunci umum sertifikat Anda.

Contoh berikut menunjukkan bagian Deskriptor Kunci dari metadata SAML yang digunakan untuk enkripsi:

<KeyDescriptor use="encryption">
  <KeyInfo xmlns="https://www.w3.org/2000/09/xmldsig#">
    <X509Data>
      <X509Certificate>valid certificate</X509Certificate>
    </X509Data>
  </KeyInfo>
</KeyDescriptor>

Protokol

Atribut Nama elemen Protokol perlu diatur ke SAML2.

Klaim input

Elemen InputClaims digunakan untuk mengirim sebuah NameId dalam Subjek Permintaan SAML AuthN. Untuk mencapai hal ini, tambahkan sebuah klaim input dengan PartnerClaimType yang diatur ke subject seperti yang ditunjukkan di bawah ini.

<InputClaims>
	<InputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="subject" />
</InputClaims>

Klaim output

Elemen OutputClaims berisi daftar klaim yang ditampilkan oleh IdP SAML di AttributeStatement pada bagian bawahnya. Anda mungkin perlu memetakan nama klaim yang ditentukan dalam kebijakan Anda ke nama yang ditentukan dalam IdP. Anda juga dapat menyertakan klaim yang tidak dikembalikan oleh IdP selama Anda mengatur atribut DefaultValue.

Klaim keluaran nama subjek

Untuk membaca pernyataan SAML NameId dalam Subjek sebagai klaim yang dinormalisasi, atur klaim PartnerClaimType ke nilai atribut SPNameQualifier. Jika atribut SPNameQualifier tidak disajikan, atur klaim PartnerClaimType ke nilai atribut NameQualifier.

Pernyataan SAML:

<saml:Subject>
  <saml:NameID SPNameQualifier="http://your-idp.com/unique-identifier" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">david@contoso.com</saml:NameID>
  <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
    <SubjectConfirmationData InResponseTo="_cd37c3f2-6875-4308-a9db-ce2cf187f4d1" NotOnOrAfter="2020-02-15T16:23:23.137Z" Recipient="https://your-tenant.b2clogin.com/your-tenant.onmicrosoft.com/B2C_1A_TrustFrameworkBase/samlp/sso/assertionconsumer" />
    </SubjectConfirmation>
  </saml:SubjectConfirmation>
</saml:Subject>

Klaim output:

<OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="http://your-idp.com/unique-identifier" />

Jika kedua atribut SPNameQualifier atau NameQualifier tidak disajikan dalam pernyataan SAML, atur klaim PartnerClaimType ke assertionSubjectName. Pastikan NameId adalah nilai pertama dalam XML pernyataan. Saat Anda menentukan lebih dari satu pernyataan, Azure AD B2C memilih nilai subjek dari pernyataan terakhir.

Contoh berikut menunjukkan klaim yang dikembalikan oleh IdP SAML:

Klaim issuerUserId dipetakan ke klaim assertionSubjectName.
Klaim first_name dipetakan ke klaim givenName.
Klaim last_name dipetakan ke klaim surname.
Klaim displayName dipetakan ke klaim name.
Klaim email tanpa pemetaan nama.

Profil teknis juga menampilkan klaim yang tidak ditampilkan oleh IdP:

Klaim identityProvider yang berisi nama IdP.
Klaim authenticationSource dengan nilai default socialIdpAuthentication.

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="assertionSubjectName" />
  <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="first_name" />
  <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="last_name" />
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email"  />
  <OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="contoso.com" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" />
</OutputClaims>

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

Metadata

Atribut	Diperlukan	Deskripsi
PartnerEntity	Ya	URL metadata IdP SAML. Salin metadata IdP dan tambahkan di dalam elemen CDATA `<![CDATA[Your IDP metadata]]>`. Menyematkan metadata penyedia identitas tidak disarankan. Penyedia identitas dapat mengubah pengaturan, atau memperbarui sertifikat. Jika metadata penyedia identitas telah diubah, dapatkan metadata baru dan perbarui kebijakan Anda dengan yang baru.
WantsSignedRequests	Tidak	Menunjukkan apakah profil teknis memerlukan semua permintaan autentikasi keluar untuk ditandatangani. Nilai yang mungkin: `true` atau `false`. Nilai defaultnya adalah `true`. Ketika nilai diatur ke `true`, kunci kriptografi SamlMessageSigning perlu ditentukan dan semua permintaan autentikasi keluar ditandatangani. Jika nilainya diatur ke `false`, parameter SigAlg dan Signature (untai (karakter) kueri atau parameter kiriman) dihilangkan dari permintaan. Metadata ini juga mengontrol metadata atribut AuthnRequestsSigned, yang merupakan output dalam metadata profil teknis Azure AD B2C yang dibagikan dengan IdP. Azure AD B2C tidak menandatangani permintaan jika nilai WantsSignedRequests dalam metadata profil teknis diatur ke `false` dan metadata IdP WantAuthnRequestsSigned diatur ke `false` atau tidak ditentukan.
XmlSignatureAlgorithm	Tidak	Metode yang digunakan Azure Active Directory B2C untuk menandatangani Pernyataan SAML. Metadata ini mengontrol nilai parameter SigAlg (untai (karakter) kueri atau parameter kiriman) dalam permintaan SAML. Nilai yang mungkin: `Sha256`, `Sha384`, `Sha512`, atau `Sha1` (default). Pastikan Anda mengonfigurasi algoritma tanda tangan pada kedua sisi dengan nilai yang sama. Hanya gunakan algoritma yang didukung sertifikat Anda.
WantsSignedAssertions	Tidak	Menunjukkan apakah profil teknis mengharuskan semua pernyataan masuk untuk ditandatangani. Nilai yang mungkin: `true` atau `false`. Nilai defaultnya adalah `true`. Jika nilai diatur ke `true`, semua bagian pernyataan `saml:Assertion` yang dikirim oleh IdP ke Azure AD B2C harus ditandatangani. Jika nilai diatur ke `false`, IdP tidak boleh menandatangani pernyataan, tetapi meskipun itu terjadi, Azure AD B2C tidak akan memvalidasi tanda tangan. Metadata ini juga mengontrol bendera metadata AuthnRequestsSigned, yang merupakan output dalam metadata profil teknis Azure AD B2C yang dibagikan dengan IdP. Jika Anda menonaktifkan validasi pernyataan, Anda mungkin juga ingin menonaktifkan validasi tanda tangan respons (untuk informasi selengkapnya, lihat ResponsesSigned) .
ResponsesSigned	Tidak	Nilai yang mungkin: `true` atau `false`. Nilai defaultnya adalah `true`. Jika nilai diatur ke `false`, IdP tidak boleh menandatangani pernyataan, tetapi bahkan jika itu terjadi, Azure AD B2C tidak akan memvalidasi tanda tangannya. Jika nilai diatur ke `true`, respons SAML yang dikirim oleh IdP ke Azure AD B2C ditandatangani dan harus divalidasi. Jika Anda menonaktifkan validasi pernyataan, Anda mungkin juga ingin menonaktifkan validasi tanda tangan pernyataan (untuk informasi selengkapnya, lihat WantsSignedAssertions).
WantsEncryptedAssertions	Tidak	Menunjukkan apakah profil teknis mengharuskan semua pernyataan masuk untuk dienkripsi. Nilai yang mungkin: `true` atau `false`. Nilai defaultnya adalah `false`. Jika nilai diatur ke `true`, pernyataan yang dikirim oleh IdP ke Azure AD B2C harus ditandatangani dan kunci kriptografi SamlAssertionDecryption perlu ditentukan. Jika nilai diatur ke `true`, metadata profil teknis Azure AD B2C menyertakan bagian enkripsi. IdP membaca metadata dan mengenkripsi pernyataan respons SAML dengan kunci umum yang disediakan dalam metadata profil teknis Azure AD B2C. Jika Anda mengaktifkan enkripsi pernyataan, Anda mungkin juga ingin menonaktifkan validasi tanda tangan respons (untuk informasi selengkapnya, lihat ResponsesSigned).
NameIdPolicyFormat	Tidak	Menentukan batasan pada pengidentifikasi nama yang akan digunakan untuk mewakili subjek yang diminta. Jika dihilangkan, jenis pengidentifikasi apa pun yang didukung oleh IdP untuk subjek yang diminta dapat digunakan. Contohnya:`urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` NameIdPolicyFormat dapat digunakan dengan NameIdPolicyAllowCreate. Lihat dokumentasi IdP Anda untuk panduan tentang kebijakan ID nama mana yang didukung.
NameIdPolicyAllowCreate	Tidak	Saat menggunakan NameIdPolicyFormat, Anda juga dapat menentukan properti `AllowCreate` dari NameIDPolicy. Nilai metadata ini adalah `true` atau `false` untuk menunjukkan apakah IdPnya diizinkan untuk membuat sebuah akun baru selama alur rincian masuk. Lihat dokumentasi IdP Anda untuk panduan tentang cara melakukannya.
AuthenticationRequestExtensions	Tidak	Elemen ekstensi pesan protokol opsional yang disepakati antara Azure AD B2C dan IdP. Ekstensi disajikan dalam format XML. Anda menambahkan data XML di dalam elemen CDATA `<![CDATA[Your IDP metadata]]>`. Periksa dokumentasi IdP Anda untuk melihat apakah elemen ekstensi didukung.
IncludeAuthnContextClassReferences	Tidak	Menentukan satu atau beberapa referensi URI yang mengidentifikasi kelas konteks autentikasi. Misalnya, untuk mengizinkan seorang pengguna untuk masuk dengan nama pengguna dan kata sandi saja, atur nilainya ke `urn:oasis:names:tc:SAML:2.0:ac:classes:Password`. Untuk mengizinkan rincian masuk melalui nama pengguna dan kata sandi selama sesi yang dilindungi (SSL/ TLS), tentukan `PasswordProtectedTransport`. Lihat dokumentasi IdP Anda untuk panduan tentang URI AuthnContextClassRef yang didukung. Tentukan beberapa URI sebagai sebuah daftar berbatas koma.
IncludeKeyInfo	Tidak	Menunjukkan apakah permintaan autentikasi SAML berisi kunci umum sertifikat ketika pengikatan diatur ke `HTTP-POST`. Nilai yang mungkin: `true` atau `false`.
IncludeClaimResolvingInClaimsHandling	Tidak	Untuk klaim input dan output, menentukan apakah resolusi klaim disertakan dalam profil teknis atau tidak. Kemungkinan nilai: `true`, atau `false` (default). Jika Anda ingin menggunakan penyelesai klaim di profil teknis, atur ini ke `true`.
SingleLogoutEnabled	Tidak	Menunjukkan apakah selama rincian masuk profil teknis mencoba untuk keluar dari IdP yang terfederasi. Untuk informasi selengkapnya, lihat Sesi keluar Azure AD B2C. Nilai yang mungkin: `true` (default), atau `false`.
ForceAuthN	Tidak	Melewati nilai ForceAuthN dalam permintaan autentikasi SAML untuk menentukan apakah IDP SAML eksternal akan dipaksa untuk meminta autentikasi pengguna. Secara default, Azure Active Directory B2C menetapkan nilai ForceAuthN untuk menjadi salah dalam masuk awal. Jika sesi kemudian diatur ulang (misalnya dengan menggunakan `prompt=login` OIDC) maka nilai ForceAuthN akan diatur ke `true`. Mengatur item metadata seperti yang ditunjukkan di bawah ini akan memaksa nilai untuk semua permintaan berpindah ke IDP eksternal. Nilai yang mungkin: `true` atau `false`.
ProviderName	Tidak	Melewati nilai ProviderName dalam permintaan autentikasi SAML.

Kunci kriptografi

Elemen CryptographicKeys berisi atribut berikut:

Atribut	Diperlukan	Deskripsi
SamlMessageSigning	Ya	Sertifikat X509 (set kunci RSA) yang digunakan untuk menandatangani pesan SAML. Azure AD B2C menggunakan kunci ini untuk menandatangani permintaan dan mengirimkannya ke IdP.
SamlAssertionDecryption	Tidak*	Sertifikat X509 (set kunci RSA). Sebuah IdP SAML menggunakan bagian publik sertifikat untuk mengenkripsi pernyataan respons SAML. Azure AD B2C menggunakan bagian privat sertifikat untuk mendekripsi pernyataan tersebut. * Diperlukan jika IDP eksternal mengenkripsi pernyataan SAML.
MetadataSigning	Tidak	Sertifikat X509 (set kunci RSA) yang digunakan untuk menandatangani metadata SAML. Azure Active Directory B2C menggunakan kunci ini untuk menandatangani metadata.

Langkah berikutnya

Lihat artikel berikut ini untuk contoh bekerja dengan IdP SAML di Azure AD B2C:

Bagikan melalui