Konfigurasikan dekripsi token di Microsoft. Identity.Web

Artikel ini menjelaskan cara mengonfigurasi sertifikat dekripsi token di Microsoft. Identity.Web sehingga aplikasi Anda dapat mendekripsi token terenkripsi dari platform identitas Microsoft.

Secara default, platform identitas Microsoft mengeluarkan token (token ID, token SAML) sebagai JWT yang ditandatangani tetapi tidak terenkripsi. Perantara apa pun yang mencegat token dapat membaca klaimnya. Untuk aplikasi yang menangani klaim sensitif atau beroperasi di lingkungan kepatuhan yang ketat, platform identitas Microsoft mendukung enkripsi token. Saat diaktifkan, platform identitas mengenkripsi payload token menggunakan kunci publik yang terdaftar di aplikasi Anda. Hanya aplikasi Anda—yang menyimpan kunci privat yang sesuai—yang dapat mendekripsi dan membaca token.

Cara kerja enkripsi token

Anda membuat sertifikat dengan pasangan kunci publik/privat.
Anda mengunggah kunci public (file .cer) ke pendaftaran aplikasi Anda di Microsoft Entra ID.
Saat platform identitas Microsoft mengeluarkan token untuk aplikasi Anda, token tersebut dienkripsi menggunakan kunci publik Anda.
Aplikasi Anda menggunakan kunci privat untuk mendekripsi token sebelum memproses klaim.

Enkripsi menggunakan skema dua lapisan: payload token dienkripsi dengan kunci enkripsi konten yang bersifat simetris, yang dibungkus atau dienkripsi menggunakan kunci publik Anda. Microsoft Entra mendukung algoritma pembungkus kunci RSA-OAEP dan RSA-OAEP-256.

Menentukan kapan harus mengonfigurasi dekripsi token

Konfigurasikan dekripsi token saat aplikasi Anda memenuhi salah satu kondisi berikut:

Menerima token SAML terenkripsi — Aplikasi perusahaan yang menggunakan akses menyeluruh berbasis SAML dan memerlukan pernyataan SAML terenkripsi untuk alasan kepatuhan atau peraturan.
Menerima token ID terenkripsi — Aplikasi web yang ikut serta dalam enkripsi token ID untuk melindungi klaim sensitif (keanggotaan grup, klaim kustom) agar tidak dibaca saat transit.
Beroperasi di lingkungan keamanan tinggi — Aplikasi dalam skenario pemerintah, keuangan, atau layanan kesehatan di mana kerahasiaan token diamanatkan oleh kebijakan.

Nota

Enkripsi token bersifat opsional. Sebagian besar aplikasi tidak membutuhkannya. Hanya aktifkan enkripsi token jika Anda memiliki persyaratan tertentu, karena menambahkan kompleksitas operasional (manajemen sertifikat, rotasi) dan membuat pemecahan masalah lebih sulit.

Memenuhi prasyarat

Sebelum Anda mengonfigurasi dekripsi token, verifikasi persyaratan berikut:

sertifikat An X.509 dengan kunci privat — Anda memerlukan sertifikat dalam format .pfx (PKCS#12) atau disimpan di lokasi yang dapat diakses oleh aplikasi Anda (Azure Key Vault, penyimpanan sertifikat, atau sistem file). Kunci privat diperlukan untuk mendekripsi token.
Pendaftaran aplikasi yang dikonfigurasi untuk enkripsi token — Unggah kunci umum sertifikat ke pendaftaran aplikasi Anda di Microsoft Entra ID. Lihat Mendaftarkan sertifikat dekripsi nanti di artikel ini.
Microsoft. Identity.Web 2.1.0 atau yang lebih baru — Properti konfigurasi TokenDecryptionCredentials tersedia di Microsoft. Identity.Web 2.1.0 dan yang lebih baru.

Mengonfigurasi dekripsi token di appsettings.json

Microsoft. Identity.Web menggunakan array TokenDecryptionCredentials di bagian konfigurasi AzureAd Anda. Array ini mengikuti format deskripsi kredensial yang sama dengan ClientCredentials, sehingga Anda dapat memuat sertifikat dekripsi dari Azure Key Vault, penyimpanan sertifikat, jalur file, atau string yang dikodekan Base64.

Menyiapkan konfigurasi dasar

Contoh berikut menunjukkan konfigurasi minimum untuk memuat sertifikat dekripsi dari Azure Key Vault:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "CallbackPath": "/signin-oidc",

    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "MyCertificate"
      }
    ]
  }
}

Tidak diperlukan kode tambahan. Saat Microsoft. Identity.Web mendeteksi konfigurasi TokenDecryptionCredentials, secara otomatis memuat sertifikat yang ditentukan dan mendaftarkannya dengan handler autentikasi OpenID Connect untuk dekripsi token.

Pilih sumber kredensial

Array TokenDecryptionCredentials mendukung jenis sumber yang sama dengan ClientCredentials. Tabel berikut ini meringkas setiap opsi:

Jenis Sumber	Deskripsi	Properti yang diperlukan
KeyVault	Muat sertifikat dari Azure Key Vault. Direkomendasikan untuk penggunaan di lingkungan produksi.	`KeyVaultUrl`, `KeyVaultCertificateName`
SimpanDenganSidikJari	Memuat dari penyimpanan sertifikat lokal dengan thumbprint.	`CertificateStorePath`, `CertificateThumbprint`
StoreWithDistinguishedName	Muat dari penyimpanan sertifikat lokal berdasarkan nama khusus subjek.	`CertificateStorePath`, `CertificateDistinguishedName`
Jalur	Memuat file `.pfx` dari sistem berkas.	`CertificateDiskPath`, `CertificatePassword`
Base64Encoded	Muat dari string yang dikodekan `.pfx` Base64 (berguna untuk variabel lingkungan).	`Base64EncodedValue`

Key Vault (disarankan untuk produksi)

Konfigurasi berikut memuat sertifikat dekripsi dari Azure Key Vault:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert"
    }
  ]
}

Identitas terkelola atau prinsipal layanan aplikasi Anda harus memiliki izin Get dan List pada sertifikat Key Vault.

Penyimpanan sertifikat (Windows)

Konfigurasi berikut memuat sertifikat dari penyimpanan sertifikat Windows dengan sidik jari:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "StoreWithThumbprint",
      "CertificateStorePath": "CurrentUser/My",
      "CertificateThumbprint": "A1B2C3D4E5F6..."
    }
  ]
}

Lintasan file

Konfigurasi berikut memuat sertifikat dari .pfx file pada disk:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Path",
      "CertificateDiskPath": "/var/ssl/private/decrypt-cert.pfx",
      "CertificatePassword": "your-certificate-password"
    }
  ]
}

Peringatan

Hindari menyimpan kata sandi sertifikat dalam appsettings.json pada lingkungan produksi. Gunakan variabel lingkungan, referensi Azure Key Vault, atau manajer rahasia sebagai gantinya.

Dikodekan dengan Base64

Konfigurasi berikut memuat sertifikat dari string yang dikodekan Base64:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Base64Encoded",
      "Base64EncodedValue": "MIIJ..."
    }
  ]
}

Opsi ini berguna saat Anda menyuntikkan sertifikat melalui variabel lingkungan atau rahasia alur CI/CD.

Mengonfigurasi beberapa sertifikat dekripsi

Anda dapat menentukan beberapa sertifikat dalam TokenDecryptionCredentials array. Microsoft. Identity.Web mencoba setiap sertifikat secara berurutan hingga berhasil mendekripsi token. Kemampuan ini sangat penting untuk rotasi sertifikat (lihat Rotasi sertifikat).

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-New"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-Old"
    }
  ]
}

Mendaftarkan sertifikat dekripsi di Microsoft Entra ID

Agar platform identitas Microsoft mengenkripsi token untuk aplikasi, Anda harus mengunggah kunci publik sertifikat ke pendaftaran aplikasi Anda:

Masuk ke pusat admin Microsoft Entra.
Navigasi ke Identity>Aplikasi>Pendaftaran aplikasi dan pilih aplikasi Anda.
Pilih Sertifikat & rahasia>Sertifikat>Unggah sertifikat.
.cer Unggah file (hanya kunci publik) sertifikat dekripsi Anda.
Setelah mengunggah, perhatikan nilai Thumbprint — nilai tersebut harus cocok dengan sertifikat yang digunakan aplikasi Anda.

Mengaktifkan enkripsi token untuk aplikasi

Setelah mengunggah sertifikat, Anda harus mengonfigurasi aplikasi untuk menerima token terenkripsi. Konfigurasi ini saat ini tersedia melalui Microsoft Graph API atau PowerShell:

Gunakan Microsoft Graph PowerShell:

# Get the key credential ID of the uploaded certificate
$app = Get-MgApplication -Filter "appId eq 'your-client-id'"
$keyId = ($app.KeyCredentials | Where-Object { $_.DisplayName -eq "CN=TokenDecryptionCert" }).KeyId

# Set the token encryption key ID
Update-MgApplication -ApplicationId $app.Id -BodyParameter @{
    "tokenEncryptionKeyId" = $keyId
}

Penting

Properti tokenEncryptionKeyId pada objek aplikasi mengidentifikasi sertifikat yang diunggah yang Microsoft Entra gunakan untuk mengenkripsi token. Hanya satu kunci enkripsi yang dapat aktif pada satu waktu.

Memutar sertifikat dekripsi

Rotasi sertifikat untuk dekripsi token memerlukan pendekatan yang cermat dan bertahap untuk menghindari downtime:

Langkah-langkah rotasi

Buat sertifikat baru — Buat sertifikat X.509 baru dengan kunci privat.
Tambahkan sertifikat baru ke konfigurasi aplikasi Anda — Tambahkan sertifikat baru ke TokenDecryptionCredentials array bersama sertifikat yang ada. Tempatkan sertifikat baru terlebih dahulu dalam array.
Unggah kunci publik baru — Unggah file .cer sertifikat baru ke pendaftaran aplikasi Anda di Microsoft Entra.
Sebarkan aplikasi Anda — Sebarkan konfigurasi yang diperbarui sehingga aplikasi Anda dapat mendekripsi token dengan salah satu sertifikat.
Alihkan kunci enkripsi aktif — Perbarui tokenEncryptionKeyId pada objek aplikasi untuk menunjuk ke sertifikat keyIdbaru .
Verifikasi — Konfirmasikan bahwa aplikasi Anda berhasil mendekripsi token yang dienkripsi dengan sertifikat baru.
Hapus sertifikat lama — Setelah masa tenggang (setidaknya 24 jam untuk memungkinkan token yang di-cache kedaluwarsa), hapus sertifikat lama dari pendaftaran aplikasi dan konfigurasi aplikasi Anda.

Konfigurasi selama rotasi

Selama jendela rotasi, TokenDecryptionCredentials Anda harus mencakup kedua sertifikat:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2026"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2025"
    }
  ]
}

Petunjuk / Saran

Otomatiskan rotasi sertifikat dengan menggunakan fitur rotasi otomatis Azure Key Vault yang dikombinasikan dengan pemberitahuan peristiwa Key Vault untuk memicu penyebaran ulang aplikasi.

Memecahkan masalah dekripsi token

Gunakan panduan berikut untuk mendiagnosis dan mengatasi masalah dekripsi token umum.

Kegagalan dekripsi token

Gejala: Aplikasi Anda melempar SecurityTokenDecryptionFailedException atau mengembalikan kesalahan 401/500 saat memproses token.

Penyebab umum:

Penyebab	Solusi
Sertifikat tidak ditemukan	Verifikasi bahwa sertifikat ada di lokasi yang dikonfigurasi (Key Vault, penyimpanan, atau jalur file). Periksa apakah aplikasi Anda memiliki izin yang diperlukan untuk mengaksesnya.
Sertifikat salah	Pastikan bahwa sidik jari sertifikat dalam konfigurasi aplikasi Anda cocok dengan sertifikat yang diunggah ke pendaftaran aplikasi.
`tokenEncryptionKeyId` tidak diatur	Atur properti `tokenEncryptionKeyId` pada objek aplikasi di Microsoft Entra. Tanpa properti ini, platform identitas tidak mengenkripsi token.

Kunci privat hilang

Gejala:CryptographicException: The certificate key is not accessible atau InvalidOperationException: Certificate does not have a private key.

Penyebab dan solusi:

Sertifikat yang diekspor tanpa kunci privat — Ekspor ulang sertifikat dalam .pfx format dan pastikan Anda menyertakan kunci privat selama ekspor.
Key Vault kebijakan akses — Saat menggunakan Azure Key Vault, pastikan identitas aplikasi Anda memiliki izin Get pada Certificates dan Secrets. Kunci privat disimpan sebagai rahasia dalam Key Vault.
Certificate store permissions — Pada Windows, verifikasi bahwa identitas kumpulan aplikasi atau akun layanan memiliki akses membaca ke kunci pribadi. Gunakan opsi Kelola Kunci Privat di penyimpanan sertifikat snap-in MMC.

Ketidakcocokan algoritma

Gejala:SecurityTokenDecryptionFailedException dengan pesan yang menunjukkan algoritma yang tidak didukung.

Penyebab dan solusi:

Jenis kunci tidak didukung — Microsoft Entra mendukung sertifikat RSA untuk enkripsi token. Pastikan sertifikat Anda menggunakan pasangan kunci RSA (bukan EC/ECDSA).
Ukuran kunci terlalu kecil — Gunakan ukuran kunci setidaknya 2048 bit. Kunci RSA yang lebih kecil dari 2048 bit mungkin ditolak.
Algorithm tidak didukung — Microsoft Entra menggunakan RSA-OAEP untuk pembungkusan kunci. Pastikan sertifikat dan infrastruktur aplikasi Anda mendukung algoritma ini.

Token terenkripsi tidak dikeluarkan

Gejala: Aplikasi Anda menerima token yang tidak terenkripsi meskipun Anda mengonfigurasi dekripsi token.

Penyebab dan solusi:

tokenEncryptionKeyId tidak dikonfigurasi — Anda harus secara eksplisit mengatur properti ini melalui Microsoft Graph. Mengunggah sertifikat saja tidak cukup.
Sertifikat kedaluwarsa dalam pendaftaran aplikasi — Verifikasi bahwa sertifikat yang diunggah ke pendaftaran aplikasi Anda belum kedaluwarsa. Unggah sertifikat baru jika diperlukan.
Token akses tidak dienkripsi — Enkripsi token hanya berlaku untuk token ID dan token SAML . Token akses dari Microsoft Entra tidak dienkripsi dengan sertifikat Anda.

Membandingkan dekripsi token dan kredensial klien

Kredensial dekripsi token melayani tujuan yang berbeda dari kredensial klien. Aplikasi Anda dapat menggunakan sertifikat yang sama untuk keduanya, atau menggunakan sertifikat terpisah.

Contoh berikut menunjukkan konfigurasi yang menggunakan sertifikat Key Vault yang sama untuk autentikasi dan dekripsi token:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ],
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ]
  }
}

Nota

Ketika Anda menggunakan sertifikat yang sama untuk kedua tujuan, sertifikat harus memiliki KeyEncipherment penggunaan kunci dan menggunakan KeyExchange spesifikasi kunci (bukan Signature). Sertifikat yang dihasilkan dengan KeySpec = Signature berfungsi untuk kredensial klien tetapi gagal dalam mendekripsi token.

Ikuti praktik terbaik

Terapkan rekomendasi ini saat Anda menerapkan dekripsi token.

Gunakan Azure Key Vault — Menyimpan sertifikat dekripsi di Key Vault untuk manajemen terpusat, kontrol akses, dan pengelogan audit.

Rencanakan rotasi — Selalu miliki strategi rotasi sebelum menyebarkan enkripsi token. Sertakan sertifikat baru dan lama selama jendela rotasi.

Gunakan kunci RSA 2048-bit atau yang lebih besar — Pastikan sertifikat Anda menggunakan kunci RSA setidaknya 2048 bit untuk keamanan yang memadai.

Monitor kedaluwarsa sertifikat — Siapkan pemberitahuan di Azure Key Vault atau sistem pemantauan Anda untuk memberi tahu Anda sebelum sertifikat kedaluwarsa.

Uji di lingkungan penahapan — Verifikasi enkripsi dan dekripsi token di lingkungan non-produksi sebelum mengaktifkannya dalam produksi.

Tidak menyimpan kunci privat dalam kontrol sumber — Gunakan Key Vault, variabel lingkungan, atau manajer rahasia untuk penyimpanan sertifikat.

Jangan menghapus sertifikat lama terlalu dini selama rotasi — Biarkan kedua sertifikat tetap aktif setidaknya selama 24 jam agar token yang di-cache kedaluwarsa.

Jangan aktifkan enkripsi token tanpa sertifikat dekripsi yang dikonfigurasi — Aplikasi Anda akan gagal memproses token jika tidak dapat mendekripsinya.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-19

Konfigurasikan dekripsi token di Microsoft. Identity.Web

Cara kerja enkripsi token

Menentukan kapan harus mengonfigurasi dekripsi token

Memenuhi prasyarat

Mengonfigurasi dekripsi token di appsettings.json

Menyiapkan konfigurasi dasar

Pilih sumber kredensial

Key Vault (disarankan untuk produksi)

Penyimpanan sertifikat (Windows)

Lintasan file

Dikodekan dengan Base64

Mengonfigurasi beberapa sertifikat dekripsi

Mendaftarkan sertifikat dekripsi di Microsoft Entra ID

Mengaktifkan enkripsi token untuk aplikasi

Memutar sertifikat dekripsi

Langkah-langkah rotasi

Konfigurasi selama rotasi

Memecahkan masalah dekripsi token

Kegagalan dekripsi token

Kunci privat hilang

Ketidakcocokan algoritma

Token terenkripsi tidak dikeluarkan

Membandingkan dekripsi token dan kredensial klien

Ikuti praktik terbaik

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: