Informasi masuk sertifikat autentikasi aplikasi platform identitas Microsoft

Artikel
04/10/2024

Platform identitas Microsoft memungkinkan aplikasi menggunakan kredensialnya sendiri untuk autentikasi di mana pun rahasia klien dapat digunakan, misalnya, dalam alur pemberian kredensial klien OAuth 2.0 dan alur atas nama (OBO).

Salah satu bentuk informasi masuk yang dapat digunakan oleh aplikasi untuk autentikasi adalah pernyataan JSON Web Token (JWT) yang ditandatangani dengan sertifikat yang dimiliki aplikasi. Hal ini dijelaskan dalam spesifikasi OpenID Connect untuk opsi autentikasi klien private_key_jwt.

Jika Anda tertarik untuk menggunakan JWT yang diterbitkan oleh penyedia identitas lain sebagai kredensial aplikasi Anda, lihat federasi identitas beban kerja untuk cara menyiapkan kebijakan federasi.

Format pernyataan

Untuk menghitung pernyataan, Anda dapat menggunakan salah satu dari banyak pustaka JWT dalam bahasa pilihan Anda - MSAL mendukung penggunaan ini .WithCertificate(). Informasi dibawa oleh token di Header, Claims, dan Signature.

Parameter	Komentar
`alg`	Harusnys RS256
`typ`	Harusnya JWT
`x5t`	Thumbprint SHA-1 yang dikodekan Base64url dari pengodean DER sertifikat X.509. Misalnya, mengingat hash sertifikat X.509 dari `84E05C1D98BCE3A5421D225B140B36E86A3D5534` (Hex), klaim `x5t` adalah `hOBcHZi846VCHSJbFAs26Go9VTQ` (Base64url).

Klaim (payload)

Jenis klaim	Nilai	Deskripsi
`aud`	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`	Klaim "aud" (audiens) mengidentifikasi penerima yang dimaksudkan JWT (di sini ID Microsoft Entra) Lihat RFC 7519, Bagian 4.1.3. Dalam hal ini, penerima tersebut adalah server masuk (login.microsoftonline.com).
`exp`	1601519414	Klaim "exp" (waktu kedaluwarsa) mengidentifikasi waktu kedaluwarsa yang pada atau setelahnya JWT tidak boleh diterima untuk pemrosesan. Lihat RFC 7519, Bagian 4.1.4. Ini memungkinkan pernyataan untuk digunakan sampai saat itu, jadi pastikan tetap pendek - paling lama 5-10 menit setelah `nbf`. ID Microsoft Entra tidak membatasi `exp` waktu saat ini.
`iss`	{ClientID}	Klaim "iss" (penerbit) mengidentifikasi perwakilan yang menerbitkan JWT, dalam kasus ini, aplikasi klien Anda. Gunakan ID aplikasi GUID.
`jti`	(Guid)	Klaim "jti" (ID JWT) memberi pengidentifikasi unik untuk JWT. Nilai pengidentifikasi harus ditetapkan dengan cara yang memastikan bahwa ada probabilitas yang dapat diabaikan bahwa nilai yang sama akan secara tidak sengaja ditetapkan ke objek data yang berbeda; jika aplikasi menggunakan beberapa penerbit, tabrakan HARUS dicegah di antara nilai yang dihasilkan oleh penerbit yang berbeda juga. Nilai "jti" adalah untai (karakter) peka huruf besar/kecil. RFC 7519, Bagian 4.1.7
`nbf`	1601519114	Klaim "nbf" (bukan sebelumnya) mengidentifikasi waktu sebelumnya yang di mana JWT TIDAK BOLEH diterima untuk diproses. RFC 7519, Bagian 4.1.5. Menggunakan waktu saat ini adalah hal yang tepat.
`sub`	{ClientID}	Klaim "sub" (subjek) mengidentifikasi subjek JWT, dalam kasus ini, aplikasi Anda termasuk. Gunakan nilai yang sama dengan `iss`.
`iat`	1601519114	Klaim "iat" (dikeluarkan di) mengidentifikasi waktu saat JWT dikeluarkan. Klaim ini dapat digunakan untuk menentukan usia JWT. RFC 7519, Bagian 4.1.5.

Tanda Tangan

Tanda tangan dihitung dengan menerapkan sertifikat seperti yang dijelaskan dalam spesifikasi JSON Web Token RFC7519.

Contoh pernyataan JWT yang didekodekan

{
  "alg": "RS256",
  "typ": "JWT",
  "x5t": "gx8tGysyjcRqKjFPnd7RFwvwZI0"
}
.
{
  "aud": "https: //login.microsoftonline.com/contoso.onmicrosoft.com/oauth2/v2.0/token",
  "exp": 1484593341,
  "iss": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "jti": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
  "nbf": 1484592741,
  "sub": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}
.
"A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u..."

Contoh pernyataan JWT yang dienkodekan

String berikut adalah contoh pernyataan yang dienkodekan. Jika Anda melihat dengan cermat, Anda melihat tiga bagian dipisahkan oleh titik (.):

Bagian pertama mengenkodekan header
Bagian kedua mengenkodekan klaim (payload)
Bagian terakhir adalah tanda tangan yang dihitung dengan sertifikat dari konten dua bagian pertama

"eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJhdWQiOiJodHRwczpcL1wvbG9naW4ubWljcm9zb2Z0b25saW5lLmNvbVwvam1wcmlldXJob3RtYWlsLm9ubWljcm9zb2Z0LmNvbVwvb2F1dGgyXC90b2tlbiIsImV4cCI6MTQ4NDU5MzM0MSwiaXNzIjoiOTdlMGE1YjctZDc0NS00MGI2LTk0ZmUtNWY3N2QzNWM2ZTA1IiwianRpIjoiMjJiM2JiMjYtZTA0Ni00MmRmLTljOTYtNjVkYmQ3MmMxYzgxIiwibmJmIjoxNDg0NTkyNzQxLCJzdWIiOiI5N2UwYTViNy1kNzQ1LTQwYjYtOTRmZS01Zjc3ZDM1YzZlMDUifQ.
Gh95kHCOEGq5E_ArMBbDXhwKR577scxYaoJ1P{a lot of characters here}KKJDEg"

Daftarkan sertifikat Anda dengan platform identitas Microsoft

Anda dapat mengaitkan kredensial sertifikat dengan aplikasi klien di platform identitas Microsoft melalui pusat admin Microsoft Entra menggunakan salah satu metode berikut:

Mengunggah file sertifikat

Di tab Pendaftaran aplikasi untuk aplikasi klien:

Pilih Sertifikat & rahasia>Sertifikat.
Pilih Unggah sertifikat dan pilih file sertifikat yang akan diunggah.
Pilih Tambahkan. Setelah sertifikat diunggah, thumbprint, tanggal mulai, dan nilai kadaluwarsa ditampilkan.

Memperbarui manifes aplikasi

Setelah memperoleh sertifikat, hitung nilai-nilai ini:

$base64Thumbprint - Nilai yang dienkodekan dengan Base64 dari hash sertifikat
$base64Value - Nilai yang dienkodekan dengan Base64 dari data mentah sertifikat

Sediakan GUID untuk mengidentifikasi kunci dalam manifes aplikasi ($keyId).

Di pendaftaran aplikasi Azure untuk aplikasi klien:

Pilih Manifest (Manifes) untuk membuka manifes aplikasi.

Ganti properti keyCredentials dengan informasi sertifikat baru Anda menggunakan skema berikut.

"keyCredentials": [
    {
        "customKeyIdentifier": "$base64Thumbprint",
        "keyId": "$keyid",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value":  "$base64Value"
    }
]

Simpan pengeditan ke manifes aplikasi lalu unggah manifes ke platform identitas Microsoft.

Properti keyCredentials ini bernilai banyak, sehingga Anda dapat mengunggah beberapa sertifikat untuk manajemen kunci yang lebih kaya.

Menggunakan pernyataan klien

Pernyataan klien dapat digunakan di mana saja rahasia klien akan digunakan. Misalnya, dalam alur kode otorisasi, Anda dapat meneruskan client_secret untuk membuktikan bahwa permintaan berasal dari aplikasi Anda. Anda dapat mengganti ini dengan parameter client_assertion dan client_assertion_type.

Parameter	Nilai	Deskripsi
`client_assertion_type`	`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`	Ini adalah nilai tetap, menunjukkan bahwa Anda menggunakan kredensial sertifikat.
`client_assertion`	`JWT`	Ini adalah JWT yang dibuat di atas.

Langkah berikutnya

Pustaka MSAL.NET menangani skenario ini dalam satu baris kode.

Aplikasi konsol daemon .NET menggunakan sampel kode platform identitas Microsoft di GitHub menunjukkan bagaimana aplikasi menggunakan kredensialnya sendiri untuk autentikasi. Ini juga menunjukkan bagaimana Anda dapat membuat sertifikat yang ditandatangani sendiri menggunakan cmdlet PowerShell New-SelfSignedCertificate. Anda juga dapat menggunakan skrip pembuatan aplikasi dalam repo sampel untuk membuat sertifikat, menghitung sidik jari, dan sebagainya.