Menentukan profil teknis petunjuk token ID dalam kebijakan kustom Azure Active Directory B2C

Artikel
01/11/2024

Azure AD B2C memungkinkan aplikasi pihak yang mengandalkan untuk mengirim JWT masuk sebagai bagian dari permintaan otorisasi OAuth2. Token JWT dapat dikeluarkan oleh aplikasi pihak yang mengandalkan atau penyedia identitas, dan dapat memberikan petunjuk tentang pengguna atau permintaan otorisasi. Azure AD B2C memvalidasi tanda tangan, nama penerbit (yang mengeluarkan), dan audiens token, dan mengekstrak klaim dari token masuk.

Kasus penggunaan

Anda dapat menggunakan solusi ini untuk mengirim data ke Azure AD B2C yang dienkapsulasi dalam satu token JWT. Signup with email invitationSolusi, tempat admin sistem Anda dapat mengirim undangan yang ditandatangani kepada pengguna, didasarkan pada id_token_hint. Hanya pengguna yang memiliki akses ke email undangan yang dapat membuat akun di dalam direktori.

Pendekatan penandatanganan token

Dengan id_token_hint, penerbit token (aplikasi pihak yang mengandalkan atau penyedia identitas) menyusun token, dan kemudian menandatanganinya menggunakan kunci penandatanganan untuk membuktikan bahwa token berasal dari sumber tepercaya. Kunci penandatanganan dapat bersifat simetris atau asimetris. Kriptografi simetris, atau kriptografi kunci pribadi, menggunakan rahasia bersama guna menandatangani maupun memvalidasi tanda tangan. Kriptografi asimetris, atau kriptografi kunci publik, adalah sistem kriptografi yang menggunakan kunci pribadi maupun kunci publik. Kunci pribadi hanya diketahui oleh penerbit token dan digunakan untuk menandatangani token. Kunci publik dibagikan dengan kebijakan Azure AD B2C untuk memvalidasi tanda tangan token.

Format token

Id_token_hint harus berupa token JWT yang valid. Tabel berikut berisi klaim yang wajib. Klaim tambahan bersifat opsional.

Nama	Klaim	Contoh nilai	Deskripsi
Audiens	`aud`	`a489fc44-3cc0-4a78-92f6-e413cd853eae`	Mengidentifikasi penerima token yang dimaksud. Audiens adalah string arbitrer yang ditentukan oleh penerbit token. Azure AD B2C akan memvalidasi nilai ini, dan menolak token jika tidak cocok.
Penerbit	`iss`	`https://localhost`	Mengidentifikasi layanan token keamanan (penerbit token). Penerbit adalah URI arbitrer yang ditentukan oleh penerbit token. Azure AD B2C akan memvalidasi nilai ini, dan menolak token jika tidak cocok.
Waktu kedaluwarsa	`exp`	`1600087315`	Waktu di mana token menjadi tidak valid, dinyatakan dalam satuan waktu epoch. Azure AD B2C akan memvalidasi nilai ini, dan menolak token jika tidak cocok.
Tidak sebelum	`nbf`	`1599482515`	Waktu di mana token menjadi valid, dinyatakan dalam satuan waktu epoch. Waktu yang dipakai ini biasanya sama dengan waktu saat token dikeluarkan. Azure AD B2C akan memvalidasi nilai ini, dan menolak token jika masa berlaku token tidak valid.

Token berikut adalah contoh token ID yang valid:

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "displayName": " John Smith",
  "userId": "john.s@contoso.com",
  "nbf": 1599482515,
  "exp": 1600087315,
  "iss": "https://localhost",
  "aud": "a489fc44-3cc0-4a78-92f6-e413cd853eae"
}

Protokol

Atribut Nama dari elemen Protokol perlu diatur ke None. Misalnya, protokol untuk profil teknis IdTokenHint_ExtractClaims adalah None:

<TechnicalProfile Id="IdTokenHint_ExtractClaims">
  <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
  <Protocol Name="None" />
  ...

Profil teknis dipanggil dari langkah orkestrasi dengan jenis GetClaims.

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

Klaim output

Elemen OutputClaims berisi daftar klaim yang akan diekstrak dari token JWT. Anda mungkin perlu memetakan nama klaim yang ditentukan dalam kebijakan Anda ke nama yang ditentukan dalam token JWT. Anda juga dapat menyertakan klaim yang tidak dikembalikan oleh token JWT, selama Anda mengatur atribut DefaultValue.

Metadata

Metadata berikut ini relevan saat menggunakan kunci simetris.

Atribut	Wajib	Deskripsi
penerbit	Ya	Mengidentifikasi layanan token keamanan (penerbit token). Nilai ini harus identik dengan `iss` klaim di dalam klaim token JWT.
IdTokenAudience	Ya	Mengidentifikasi penerima token yang dimaksud. Nilai ini harus identik dengan `aud` klaim di dalam klaim token JWT.

Metadata berikut ini relevan saat menggunakan kunci asimetris.

Atribut	Wajib	Deskripsi
METADATA	Ya	URL yang menunjuk kepada dokumen konfigurasi penerbit token, yang juga dikenal sebagai titik akhir konfigurasi OpenID yang telah dikenal.
penerbit	Tidak	Mengidentifikasi layanan token keamanan (penerbit token). Nilai ini dapat digunakan untuk menimpa nilai yang dikonfigurasi dalam metadata, dan harus identik dengan `iss` klaim di dalam klaim token JWT.
IdTokenAudience	Tidak	Mengidentifikasi penerima token yang dimaksud. Nilai ini harus identik dengan `aud` klaim di dalam klaim token JWT.

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.

Kunci kriptografi

Saat menggunakan kunci simetris, elemen CryptographicKeys berisi atribut berikut ini:

Atribut	Wajib	Deskripsi
client_secret	Ya	Kunci kriptografi yang digunakan untuk memvalidasi tanda tangan token JWT.

Panduan

Menerbitkan token dengan kunci simetris

Langkah 1: Membuat kunci bersama

Buatlah kunci yang dapat digunakan untuk menandatangani token. Misalnya, gunakan kode PowerShell berikut untuk membuat kunci.

$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$newClientSecret

Kode ini menghasilkan string rahasia seperti VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=.

Langkah 2: Tambahkan kunci penandatanganan ke Azure AD B2C

Kunci yang sama yang digunakan oleh penerbit token perlu dibuat di kunci kebijakan Azure AD B2C Anda.

Masuk ke portal Azure.
Jika Anda memiliki akses ke beberapa penyewa, pilih ikon Pengaturan di menu atas untuk beralih ke penyewa Azure AD B2C Anda dari menu Direktori + langganan.
Di portal Microsoft Azure, cari dan pilih AAD B2C.
Pada halaman gambaran umum, di bawah Kebijakan, pilih Kerangka Kerja Pengalaman Identitas.
Pilih Kunci Kebijakan
Pilih Manual.
Untuk Nama, gunakan IdTokenHintKey.
Prefiks B2C_1A_ mungkin ditambahkan secara otomatis.
Dalam kotak Rahasia, masukkan kunci masuk yang telah Anda buat sebelumnya.
Untuk Penggunaan kunci, gunakan Enkripsi.
Pilih Buat.
Konfirmasikan bahwa Anda telah membuat B2C_1A_IdTokenHintKey kunci.

Langkah 3: Tambahkan profil teknis petunjuk token ID

Profil teknis berikut memvalidasi token dan mengekstrak klaim.

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <Item Key="IdTokenAudience">a489fc44-3cc0-4a78-92f6-e413cd853eae</Item>
        <Item Key="issuer">https://localhost</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="client_secret" StorageReferenceId="B2C_1A_IdTokenHintKey" />
      </CryptographicKeys>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Langkah 4: Siapkan kebijakan Anda

Selesaikan langkah Konfigurasi kebijakan Anda.

Langkah 5: Siapkan kode

Sampel GitHub adalah aplikasi web ASP.NET dan konsol yang menghasilkan token ID yang ditandatangani menggunakan kunci simetris.

Menerbitkan token dengan kunci asimetris

Dengan kunci asimetris, token ditandatangani menggunakan sertifikat RSA. Aplikasi ini menghosting titik akhir metadata OpenID Koneksi dan titik akhir JSON Web Keys (JWK) yang digunakan oleh Azure AD B2C untuk memvalidasi tanda tangan token ID.

Penerbit token harus menyediakan titik akhir berikut:

/.well-known/openid-configuration - Titik akhir konfigurasi yang telah dikenal dengan informasi yang relevan tentang token, seperti nama penerbit token dan tautan ke titik akhir JWK.
/.well-known/keys - titik akhir JSON Web Key (JWK) dengan kunci publik yang digunakan untuk menandatangani kunci (dengan bagian kunci pribadi pada sertifikat).

Lihat sampel pengontrol TokenMetadataController.cs .NET MVC.

Langkah 1: Siapkan sertifikat yang ditandatangani sendiri

Jika Anda belum memiliki sertifikat, Anda dapat menggunakan sertifikat yang ditandatangani sendiri dalam panduan ini. Di Windows, Anda dapat menggunakan PowerShell New-SelfSignedCertificate cmdlet untuk membuat sertifikat.

Jalankan perintah PowerShell ini untuk membuat sertifikat yang ditandatangani sendiri. Ubahlah -Subjectargumen sesuai aplikasi Anda dan nama penyewa Azure Active Directory B2C. Anda juga dapat mengatur -NotAftertanggal untuk menetapkan waktu kedaluwarsa yang berbeda untuk sertifikat.

New-SelfSignedCertificate `
    -KeyExportPolicy Exportable `
    -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -KeyUsage DigitalSignature `
    -NotAfter (Get-Date).AddMonths(12) `
    -CertStoreLocation "Cert:\CurrentUser\My"

Langkah 2: Tambahkan profil teknis petunjuk token ID

Profil teknis berikut memvalidasi token dan mengekstrak klaim. Ubahlah URI metadata ke titik akhir konfigurasi yang telah dikenal pada penerbit token Anda.

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <!-- Replace with your endpoint location -->
        <Item Key="METADATA">https://your-app.azurewebsites.net/.well-known/openid-configuration</Item>
        <Item Key="IdTokenAudience">your_optional_audience</Item>
        <!-- <Item Key="issuer">your_optional_token_issuer_override</Item> -->
      </Metadata>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

Langkah 3: Siapkan kebijakan Anda

Selesaikan langkah Konfigurasi kebijakan Anda.

Langkah 4: Siapkan kode

Sampel GitHub ASP.NET aplikasi web ini menghasilkan token ID dan menjadi host titik akhir metadata yang diperlukan untuk menggunakan parameter "id_token_hint" di Azure AD B2C.

Mengonfigurasi kebijakan Anda

Untuk pendekatan simetris maupun asimetris, id_token_hint profil teknis dipanggil dari langkah orkestrasi dengan jenis GetClaimsdan perlu menentukan klaim input dari kebijakan pihak yang mengandalkan.

Tambahkan profil IdTokenHint_ExtractClaims ke dalam kebijakan ekstensi Anda.

Tambahkan langkah orkestrasi berikut pada perjalanan pengguna Anda sebagai item pertama.

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

Dalam kebijakan pihak yang mengandalkan Anda, ulangi klaim input yang sama yang telah Anda konfigurasi pada profil teknis IdTokenHint_ExtractClaims. Contohnya:

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUp" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <InputClaims>
      <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
    </InputClaims>
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

Tergantung pada kebutuhan bisnis Anda, mungkin validasi token perlu Anda tambahkan, misalnya memeriksa format alamat email. Untuk melakukannya, tambahkan langkah-langkah orkestrasi yang menggunakan profil teknis transformasi klaim. Tambahkan juga profil teknis yang diajukan/ditegaskan sendiri untuk memunculkan pesan kesalahan.

Buat dan Tandatangani token

Sampel GitHub menggambarkan cara membuat masalah token seperti JWT, yang kemudian dikirim sebagai id_token_hint parameter string kueri. Berikut ini adalah contoh permintaan otorisasi dengan parameter id_token_hint

https://tenant-name.b2clogin.com/tenant-name.onmicrosoft.com/B2C_1A_signup_signin/oauth2/v2.0/authorize?client_id=63ba0d17-c4ba-47fd-89e9-31b3c2734339&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaXNwbGF5TmFtZSI6IiBKb2huIFNtaXRoIiwidXNlcklkIjoiam9obi5zQGNvbnRvc28uY29tIiwibmJmIjoxNTk5NDgyNTE1LCJleHAiOjE2MDAwODczMTUsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0IiwiYXVkIjoiYTQ4OWZjNDQtM2NjMC00YTc4LTkyZjYtZTQxM2NkODUzZWFlIn0.nPmLXydI83PQCk5lRBYUZRu_aX58pL1khahHyQuupig

Langkah berikutnya

Periksa pendaftaran dengan mengundang solusi email pada repo GitHub komunitas di Azure AD B2C.

Bagikan melalui