Gunakan sertifikat dengan Microsoft. Identity.Web

Microsoft. Identity.Web mendukung autentikasi berbasis sertifikat sebagai alternatif aman untuk rahasia klien untuk aplikasi klien rahasia. Sertifikat menggunakan kriptografi asimetris, sehingga hanya pemegang kunci privat yang dapat mengautentikasi.

Dalam artikel ini, Anda mengonfigurasi kredensial sertifikat dari berbagai sumber, mendaftarkannya dengan aplikasi Anda, dan mengelolanya dalam produksi.

Mengapa menggunakan sertifikat?

Faktor	Rahasia Klien	Sertifikat
Keamanan	Rahasia bersama (simetris)	Pasangan kunci asimetris
Rotasi	Memerlukan penyebaran ulang aplikasi atau perubahan konfigurasi	Dapat diotomatisasi melalui Key Vault
Risiko paparan	Rahasia dalam konfigurasi dapat bocor	Kunci privat tetap berada di penyimpanan yang aman
Kepatuhan	Mungkin tidak memenuhi kebijakan perusahaan	Memenuhi sebagian besar persyaratan keamanan perusahaan
Disarankan untuk	Pengembangan, prototipe	Beban kerja produksi

Penting

Microsoft merekomendasikan sertifikat atas rahasia klien untuk aplikasi produksi. Untuk postur keamanan tertinggi, gunakan autentikasi tanpa sertifikat (Identitas Terkelola atau Federasi Identitas Beban Kerja) saat lingkungan hosting Anda mendukungnya.

Cara kerjanya

Anda membuat atau mendapatkan sertifikat X.509 dengan kunci privat.
Anda mendaftarkan kunci publik sertifikat (atau thumbprint) pada pendaftaran aplikasi Microsoft Entra Anda.
Saat runtime, Microsoft. Identity.Web memuat sertifikat (termasuk kunci privat) dari sumber anda yang dikonfigurasi.
Pustaka menggunakan kunci privat untuk menandatangani pernyataan klien, yang dikirimnya ke Microsoft Entra ID untuk mendapatkan token.

Sumber sertifikat

Microsoft. Identity.Web mendukung pemuatan sertifikat dari beberapa sumber:

Jenis Sumber	Nilai `SourceType`	Terbaik untuk
Azure Key Vault	`KeyVault`	Produksi (disarankan)
Toko Sertifikat	`StoreWithThumbprint` atau `StoreWithDistinguishedName`	Windows server, lokal
Lintasan file	`Path`	Pengembangan aplikasi terkontainerisasi
String yang dikodekan Base64	`Base64Encoded`	Rahasia Kubernetes, alur CI/CD

Anda mengonfigurasi kredensial sertifikat pada array ClientCertificates dalam bagian konfigurasi AzureAd atau AzureAdB2C Anda. Anda dapat menentukan beberapa sertifikat untuk skenario rotasi — Microsoft. Identity.Web menggunakan sertifikat valid pertama yang ditemukannya.

Dari Azure Key Vault (disarankan)

Azure Key Vault adalah sumber yang direkomendasikan untuk sertifikat dalam produksi. Ini menyediakan manajemen terpusat, kontrol akses, audit, dan kemampuan rotasi otomatis.

Konfigurasi

Tambahkan konfigurasi sertifikat ke appsettings.json:

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

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

Harta benda	Deskripsi
`SourceType`	Harus berupa `"KeyVault"` .
`KeyVaultUrl`	URI Azure Key Vault Anda (misalnya, `https://myapp-kv.vault.azure.net`).
`KeyVaultCertificateName`	Nama sertifikat seperti yang disimpan dalam Key Vault.

Menyiapkan kebijakan akses Key Vault

Identitas aplikasi Anda harus memiliki izin untuk membaca sertifikat dari Key Vault. Cara Anda memberikan akses ini tergantung pada apakah Anda menggunakan model kebijakan akses vault atau kontrol akses berbasis peran Azure (RBAC).

Opsi 1: Kebijakan akses brankas

az keyvault set-policy \
  --name your-keyvault-name \
  --object-id <app-or-managed-identity-object-id> \
  --certificate-permissions get list \
  --secret-permissions get

Nota

Izin --secret-permissions get diperlukan karena Azure Key Vault menyimpan kunci privat sebagai rahasia yang ditautkan ke sertifikat. Microsoft. Identity.Web memerlukan akses ke sertifikat dan kunci privatnya.

Opsi 2: Azure RBAC

Tetapkan peran Key Vault Certificate User ke identitas aplikasi Anda:

az role assignment create \
  --role "Key Vault Certificate User" \
  --assignee <app-or-managed-identity-object-id> \
  --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>

Menggunakan Identitas Terkelola untuk mengakses Key Vault

Saat aplikasi Anda berjalan di Azure (App Service, Azure Functions, Azure Kubernetes Service, VM), gunakan Identitas Terkelola untuk mengautentikasi ke Key Vault. Ini menghilangkan kebutuhan kredensial apa pun untuk mengakses vault itu sendiri.

Identitas Terkelola yang Ditentukan oleh Sistem

Jika aplikasi Anda mengaktifkan Identitas Terkelola yang ditetapkan sistem, Microsoft. Identity.Web secara otomatis menggunakan DefaultAzureCredential untuk mengautentikasi ke Key Vault. Tidak ada konfigurasi tambahan yang diperlukan di luar ClientCertificates entri:

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

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

Identitas Terkelola yang Ditetapkan Pengguna

Untuk Identitas Terkelola yang ditetapkan pengguna, tentukan ManagedIdentityClientId pada pendeskripsi sertifikat Key Vault:

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

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Petunjuk / Saran

Saat berjalan secara lokal selama pengembangan, DefaultAzureCredential kembali ke kredensial Azure CLI atau Visual Studio Anda. Pastikan Anda masuk dengan az login dan akun pengembang Anda memiliki izin Key Vault yang sesuai.

Dari penyimpanan sertifikat (hanya Windows)

Pada Windows, Anda dapat memuat sertifikat dari Windows Certificate Store. Ini umum untuk penyebaran lokal atau yang dihosting IIS.

Dengan sidik jari

Gunakan StoreWithThumbprint untuk mengidentifikasi sertifikat dengan thumbprint SHA-1-nya:

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

    "ClientCertificates": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateThumbprint": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2"
      }
    ]
  }
}

Harta benda	Deskripsi
`SourceType`	Harus berupa `"StoreWithThumbprint"` .
`CertificateStorePath`	Lokasi penyimpanan sertifikat. Nilai umum: `"CurrentUser/My"`, `"LocalMachine/My"`.
`CertificateThumbprint`	Thumbprint SHA-1 dari sertifikat (sebanyak 40 karakter hex).

Dengan nama istimewa

Gunakan StoreWithDistinguishedName untuk mengidentifikasi sertifikat dengan nama subjeknya:

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

    "ClientCertificates": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateDistinguishedName": "CN=MyAppCertificate"
      }
    ]
  }
}

Harta benda	Deskripsi
`SourceType`	Harus berupa `"StoreWithDistinguishedName"` .
`CertificateStorePath`	Lokasi penyimpanan sertifikat. Nilai umum: `"CurrentUser/My"`, `"LocalMachine/My"`.
`CertificateDistinguishedName`	Nama khusus subjek sertifikat (misalnya, `"CN=MyAppCertificate"`).

Lokasi penyimpanan sertifikat

Tabel berikut ini mencantumkan jalur penyimpanan sertifikat umum dan izin yang diperlukan untuk mengaksesnya:

Jalur	Deskripsi	Izin diperlukan
`CurrentUser/My`	Penyimpanan pribadi pengguna saat ini	Akses tingkat pengguna
`LocalMachine/My`	Penyimpanan pribadi di seluruh komputer	Akses administrator
`LocalMachine/Root`	Otoritas Sertifikat (CA) akar tepercaya	Akses administrator
`CurrentUser/Root`	CA akar tepercaya pengguna saat ini	Akses tingkat pengguna

Nota

Saat menghosting di IIS, identitas kumpulan aplikasi harus memiliki akses baca ke kunci privat sertifikat. Anda dapat memberikan ini menggunakan opsi Kelola Kunci Privat di snap-in MMC Sertifikat.

Dari jalur file

Anda dapat memuat sertifikat langsung dari .pfx file (PKCS#12) pada disk.

Peringatan

Menyimpan file sertifikat pada disk dengan kata sandi dalam konfigurasi tidak disarankan untuk produksi. Gunakan pendekatan ini hanya untuk pengembangan lokal atau di lingkungan tempat sistem file diamankan (misalnya, rahasia yang dipasang dalam kontainer).

Konfigurasi

Tambahkan jalur file sertifikat dan kata sandi ke appsettings.json:

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

    "ClientCertificates": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/path/to/certificate.pfx",
        "CertificatePassword": "your-certificate-password"
      }
    ]
  }
}

Harta benda	Deskripsi
`SourceType`	Harus berupa `"Path"` .
`CertificateDiskPath`	Jalur absolut atau relatif ke berkas `.pfx`.
`CertificatePassword`	Kata sandi untuk `.pfx` file. Jika sertifikat tidak memiliki kata sandi, hilangkan properti ini atau atur ke string kosong.

Petunjuk / Saran

Untuk menghindari penyimpanan kata sandi dalam teks biasa di appsettings.json, referensikan dari variabel lingkungan atau manajer rahasia:

Gunakan Rahasia Pengguna .NET (pengembangan):

dotnet user-secrets set "AzureAd:ClientCertificates:0:CertificatePassword" "your-password"

Menggunakan variabel lingkungan:

export AzureAd__ClientCertificates__0__CertificatePassword="your-password"

Dari nilai yang dikodekan Base64

Anda dapat memberikan sertifikat sebagai string yang dikodekan Base64. Pendekatan ini berguna ketika Anda menyuntikkan sertifikat melalui variabel lingkungan, rahasia Kubernetes, atau variabel alur CI/CD.

Konfigurasi

Tambahkan nilai sertifikat yang dikodekan Base64 ke appsettings.json:

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

    "ClientCertificates": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg..."
      }
    ]
  }
}

Harta benda	Deskripsi
`SourceType`	Harus berupa `"Base64Encoded"` .
`Base64EncodedValue`	Sertifikat lengkap (termasuk kunci privat) dikodekan sebagai string Base64.

Hasilkan nilai Base64

.pfx Mengonversi file menjadi string Base64:

PowerShell:

$certBytes = [System.IO.File]::ReadAllBytes("path/to/certificate.pfx")
$base64 = [System.Convert]::ToBase64String($certBytes)
$base64 | Set-Clipboard  # Copies to clipboard

Bash:

base64 -w 0 path/to/certificate.pfx

Gunakan dengan rahasia Kubernetes

Simpan sertifikat yang dikodekan Base64 dalam rahasia Kubernetes dan petakan ke variabel lingkungan:

apiVersion: v1
kind: Secret
metadata:
  name: app-cert-secret
type: Opaque
data:
  AzureAd__ClientCertificates__0__Base64EncodedValue: <base64-encoded-pfx>

Referensikan rahasia dalam penyebaran Anda:

env:
  - name: AzureAd__ClientCertificates__0__SourceType
    value: "Base64Encoded"
  - name: AzureAd__ClientCertificates__0__Base64EncodedValue
    valueFrom:
      secretKeyRef:
        name: app-cert-secret
        key: AzureAd__ClientCertificates__0__Base64EncodedValue

Gunakan dalam alur CI/CD

Dalam Azure DevOps atau GitHub Actions, simpan sertifikat yang dikodekan Base64 sebagai variabel rahasia, lalu atur sebagai variabel lingkungan saat runtime.

GitHub Actions contoh:

env:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: ${{ secrets.APP_CERTIFICATE_BASE64 }}

Azure DevOps contoh:

variables:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: $(AppCertificateBase64)

Penting

Meskipun sertifikat dikodekan Base64, sertifikat berisi kunci privat dan harus diperlakukan sebagai rahasia. Selalu gunakan variabel rahasia dalam alur CI/CD — jangan pernah menerapkan sertifikat yang dikodekan Base64 ke kontrol sumber.

Mengonfigurasi sertifikat dalam kode C#

Selain konfigurasi JSON, Anda dapat mengonfigurasi kredensial sertifikat secara terprogram menggunakan kelas CredentialDescription dari Microsoft.Identity.Abstractions.

Metode pembantu

Kelas ini CredentialDescription menyediakan metode pembantu statis untuk setiap jenis sumber sertifikat:

using Microsoft.Identity.Abstractions;

// From Azure Key Vault
var kvCredential = CredentialDescription.FromKeyVault(
    "https://your-keyvault-name.vault.azure.net",
    "your-certificate-name");

// From certificate store (by thumbprint)
var thumbprintCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2");

// From certificate store (by distinguished name)
var dnCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=MyAppCertificate");

// From file path
var pathCredential = CredentialDescription.FromCertificatePath(
    "/path/to/certificate.pfx",
    "your-certificate-password");

// From Base64-encoded string
var base64Credential = CredentialDescription.FromBase64String(
    "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg...");

Gunakan dalam ASP.NET Core

Berikan deskripsi kredensial secara langsung saat mengonfigurasi autentikasi:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "your-client-id";
        options.ClientCredentials = new[]
        {
            CredentialDescription.FromKeyVault(
                "https://your-keyvault-name.vault.azure.net",
                "your-certificate-name")
        };
    });

Petunjuk / Saran

Metode pembantu setara dengan mengatur properti pada CredentialDescription objek secara manual. Mereka memberikan sintaks yang lebih ringkas saat Anda mengonfigurasi kredensial dalam kode daripada melalui appsettings.json.

Membuat sertifikat yang ditandatangani sendiri untuk pengembangan

Untuk pengembangan dan pengujian lokal, Anda dapat membuat sertifikat yang ditandatangani sendiri. Jangan gunakan sertifikat yang ditandatangani sendiri dalam produksi.

Menggunakan PowerShell (Windows)

Jalankan perintah berikut untuk membuat sertifikat yang ditandatangani sendiri, mengekspornya, dan menampilkan thumbprint:

$cert = New-SelfSignedCertificate `
  -Subject "CN=MyDevCertificate" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyExportPolicy Exportable `
  -KeySpec Signature `
  -KeyLength 2048 `
  -KeyAlgorithm RSA `
  -HashAlgorithm SHA256 `
  -NotAfter (Get-Date).AddYears(2)

# Export the .pfx file (with private key)
$password = ConvertTo-SecureString -String "YourPassword123!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath ".\MyDevCertificate.pfx" -Password $password

# Export the .cer file (public key only — for app registration)
Export-Certificate -Cert $cert -FilePath ".\MyDevCertificate.cer"

# Display the thumbprint
Write-Host "Thumbprint: $($cert.Thumbprint)"

Menggunakan OpenSSL (lintas platform)

Jalankan perintah berikut untuk menghasilkan sertifikat, mengemasnya sebagai .pfx file, dan menampilkan thumbprint:

# Generate a self-signed certificate and private key
openssl req -x509 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -days 730 -nodes \
  -subj "/CN=MyDevCertificate"

# Package into a .pfx file
openssl pkcs12 -export \
  -out MyDevCertificate.pfx \
  -inkey key.pem -in cert.pem \
  -passout pass:YourPassword123!

# Get the thumbprint
openssl x509 -in cert.pem -noout -fingerprint -sha1

Menggunakan CLI .NET

Ekspor sertifikat HTTPS pengembangan sebagai .pfx file:

dotnet dev-certs https --export-path ./MyDevCertificate.pfx --password YourPassword123!

Nota

Perintah dotnet dev-certs menghasilkan sertifikat pengembangan HTTPS. Meskipun dapat digunakan untuk menguji pemuatan sertifikat, ini terutama ditujukan untuk HTTPS lokal dan mungkin tidak cocok untuk semua skenario pengujian autentikasi.

Mendaftarkan sertifikat di Microsoft Entra ID

Setelah Anda membuat atau mendapatkan sertifikat, Anda harus mendaftarkan kunci publiknya dengan pendaftaran aplikasi Anda di Microsoft Entra ID.

Menggunakan portal Azure

Buka portal Azure dan navigasikan ke Microsoft Entra ID>Pendaftaran aplikasi.
Pilih aplikasi Anda.
Pilih Sertifikat & rahasia>Sertifikat>Unggah sertifikat.
Unggah file .cer atau .pem, yang berisi kunci publik saja. Jangan unggah .pfx file, yang berisi kunci privat.
Perhatikan nilai Thumbprint yang ditampilkan setelah diunggah — Anda mungkin memerlukannya untuk konfigurasi.

Menggunakan Azure CLI

az ad app credential reset \
  --id <application-client-id> \
  --cert @/path/to/certificate.pem \
  --append

Bendera --append menambahkan sertifikat tanpa menghapus kredensial yang ada.

Menggunakan Microsoft Graph PowerShell

$certData = [System.IO.File]::ReadAllBytes(".\MyDevCertificate.cer")
$base64Cert = [System.Convert]::ToBase64String($certData)

$keyCredential = @{
    type = "AsymmetricX509Cert"
    usage = "Verify"
    key = [System.Convert]::FromBase64String($base64Cert)
    displayName = "MyAppCertificate"
}

Update-MgApplication -ApplicationId <app-object-id> -KeyCredentials @($keyCredential)

Penting

Hanya unggah kunci publik (.cer atau .pem) ke pendaftaran aplikasi. Jangan pernah mengunggah .pfx file, yang berisi kunci privat. Kunci privat harus tetap disimpan dengan aman dan hanya dapat diakses oleh aplikasi Anda.

Pergantian sertifikat

Rotasi sertifikat menggantikan sertifikat yang kedaluwarsa dengan sertifikat baru sebelum kedaluwarsa, memastikan layanan yang tidak terganggu.

Strategi: Tumpang tindih sertifikat

Pendekatan yang direkomendasikan menggunakan periode validitas yang tumpang tindih:

Buat sertifikat baru sebelum sertifikat saat ini kedaluwarsa (misalnya, 30–60 hari sebelumnya).
Daftarkan sertifikat baru pada pendaftaran aplikasi Microsoft Entra Anda bersamaan dengan yang sudah ada. Microsoft Entra ID menerima token yang ditandatangani oleh sertifikat terdaftar apa pun.
Deploy sertifikat baru ke sumber sertifikat aplikasi Anda (Key Vault, penyimpanan sertifikat, dan sebagainya).
Perbarui konfigurasi (jika perlu) untuk menunjuk ke sertifikat baru.
Hapus sertifikat lama dari pendaftaran aplikasi setelah mengonfirmasi semua instans menggunakan yang baru.

Beberapa sertifikat dalam konfigurasi

Microsoft. Identity.Web mendukung menentukan beberapa sertifikat. Pustaka mencobanya secara berurutan dan menggunakan sertifikat pertama yang valid:

{
  "AzureAd": {
    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "new-cert-2026"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "current-cert-2025"
      }
    ]
  }
}

Rotasi otomatis dengan Azure Key Vault

Azure Key Vault mendukung perpanjangan sertifikat otomatis. Saat Anda mengaktifkan rotasi otomatis:

Key Vault menghasilkan versi sertifikat baru sebelum kedaluwarsa.
Microsoft. Identity.Web mengambil versi terbaru secara otomatis (pada pengambilan sertifikat berikutnya).
Versi sertifikat lama tetap valid hingga kedaluwarsa.

Untuk mengonfigurasi rotasi otomatis di Key Vault:

az keyvault certificate set-attributes \
  --vault-name your-keyvault-name \
  --name your-certificate-name \
  --policy @rotation-policy.json

Petunjuk / Saran

Untuk aplikasi dengan proses jangka panjang, pertimbangkan untuk menerapkan refresh sertifikat berkala. Microsoft. Identity.Web menyimpan sertifikat dalam memori. Jika sertifikat diputar dalam Key Vault, aplikasi mengambil sertifikat baru saat berikutnya perlu membuat instans aplikasi klien rahasia MSAL baru.

Memecahkan masalah kesalahan sertifikat

Bagian ini mencantumkan pesan kesalahan umum dan solusinya.

Kesalahan umum

Sertifikat tidak ditemukan

Pesan kesalahan:

System.Security.Cryptography.CryptographicException: The certificate cannot be found.

Kemungkinan penyebab dan solusi:

Penyebab	Solusi
Sidik jari salah	Verifikasi sidik jari dalam pengaturan Anda cocok dengan sertifikat yang diinstal. Hapus karakter tersembunyi apa pun (spasi, Unicode tak terlihat).
Penyimpanan sertifikat salah	Konfirmasi kecocokan `CertificateStorePath` di mana sertifikat diinstal (`CurrentUser/My` vs `LocalMachine/My`).
Sertifikat tidak terinstal	Impor sertifikat ke penyimpanan yang benar menggunakan `certmgr.msc` (CurrentUser) atau `certlm.msc` (LocalMachine).
ketidakcocokan nama Key Vault	Verifikasi `KeyVaultUrl` dan `KeyVaultCertificateName` sudah benar.
File tidak ditemukan	Konfirmasi `CertificateDiskPath` poin ke sebuah file `.pfx` yang ada dan aplikasi memiliki izin akses baca.

Akses ditolak ke Key Vault

Pesan kesalahan:

Azure.RequestFailedException: The user, group or application '...' does not have certificates get permission on key vault '...'

Solusi:

Verifikasi kebijakan akses memberikan get izin untuk sertifikat dan rahasia.
Jika menggunakan RBAC Azure, pastikan identitas memiliki peran Key Vault Certificate User.
Untuk Identitas Terkelola, pastikan identitas diaktifkan dan ID objek yang tepat digunakan di dalam kebijakan.

Kunci privat sertifikat tidak dapat diakses

Pesan kesalahan:

System.Security.Cryptography.CryptographicException: Keyset does not exist.

Solusi:

Pada Windows/IIS, pastikan identitas kumpulan aplikasi memiliki akses dibaca ke kunci privat. Gunakan snap-in MMC Sertifikat untuk memberikan akses melalui Kelola Kunci Privat.
Di Linux, verifikasi bahwa .pfx file memiliki izin yang sesuai (chmod 600).
Pastikan sertifikat diekspor dengan kunci privat (Export-PfxCertificate atau openssl pkcs12 -export).

Sertifikat kedaluwarsa

Pesan kesalahan:

AADSTS700027: Client assertion contains an invalid signature. The key was expired.

Solusi:

Periksa periode validitas sertifikat: openssl x509 -in cert.pem -noout -dates.
Buat sertifikat baru dan perbarui pendaftaran aplikasi dan konfigurasi aplikasi Anda.
Terapkan rotasi sertifikat untuk mencegah masalah kedaluwarsa di masa mendatang. Lihat Pergantian sertifikat.

Kata sandi sertifikat salah

Pesan kesalahan:

System.Security.Cryptography.CryptographicException: The specified network password is not correct.

Solusi:

Verifikasi CertificatePassword cocok dengan kata sandi yang digunakan saat mengekspor .pfx file.
Jika menggunakan variabel lingkungan, periksa masalah pengodean (baris baru di akhir dan karakter khusus).
Ekspor ulang sertifikat dengan kata sandi yang diketahui.

Daftar periksa diagnostik

Gunakan daftar periksa ini saat autentikasi sertifikat tidak berfungsi:

[ ] Validitas sertifikat — Apakah sertifikat dalam periode validitasnya? Periksa tanggal NotBefore dan NotAfter.
[ ] ] Pendaftaran aplikasi — Apakah kunci publik sertifikat diunggah ke pendaftaran aplikasi yang benar?
[ ] Kecocokan Thumbprint — Apakah thumbprint dalam konfigurasi Anda sesuai dengan sertifikat dalam registrasi aplikasi?
[ ] Akses kunci privat — Dapatkah proses aplikasi membaca kunci privat sertifikat?
[ ] Key Vault izin — Untuk sumber Key Vault, apakah identitas memiliki izin certificates/get dan secrets/get?
[ ] Bagian konfigurasi — Apakah konfigurasi sertifikat di bawah bagian yang benar (AzureAd atau AzureAdB2C)?
[ ] paket NuGet — Apakah Microsoft.Identity.Web sudah diperbarui? Versi lama mungkin tidak memiliki dukungan untuk jenis sumber sertifikat tertentu.

Aktifkan pengelogan

Untuk mendapatkan informasi diagnostik terperinci, aktifkan pengelogan MSAL:

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

builder.Logging.AddFilter("Microsoft.Identity", LogLevel.Debug);

Tinjau log untuk pesan tentang pemuatan sertifikat, pembuatan pernyataan klien, dan akuisisi token.

Gambaran umum kredensial
Autentikasi tanpa sertifikat — Identitas Terkelola dan Federasi Identitas Beban Kerja
Rahasia klien — jenis kredensial alternatif untuk aplikasi rahasia
Dekripsi token — menggunakan sertifikat untuk dekripsi token
Pencatatan dan diagnostik

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-19

Gunakan sertifikat dengan Microsoft. Identity.Web

Mengapa menggunakan sertifikat?

Cara kerjanya

Sumber sertifikat

Dari Azure Key Vault (disarankan)

Konfigurasi

Menyiapkan kebijakan akses Key Vault

Opsi 1: Kebijakan akses brankas

Opsi 2: Azure RBAC

Menggunakan Identitas Terkelola untuk mengakses Key Vault

Identitas Terkelola yang Ditentukan oleh Sistem

Identitas Terkelola yang Ditetapkan Pengguna

Dari penyimpanan sertifikat (hanya Windows)

Dengan sidik jari

Dengan nama istimewa

Lokasi penyimpanan sertifikat

Dari jalur file

Konfigurasi

Dari nilai yang dikodekan Base64

Konfigurasi

Hasilkan nilai Base64

Gunakan dengan rahasia Kubernetes

Gunakan dalam alur CI/CD

Mengonfigurasi sertifikat dalam kode C#

Metode pembantu

Gunakan dalam ASP.NET Core

Membuat sertifikat yang ditandatangani sendiri untuk pengembangan

Menggunakan PowerShell (Windows)

Menggunakan OpenSSL (lintas platform)

Menggunakan CLI .NET

Mendaftarkan sertifikat di Microsoft Entra ID

Menggunakan portal Azure

Menggunakan Azure CLI

Menggunakan Microsoft Graph PowerShell

Pergantian sertifikat

Strategi: Tumpang tindih sertifikat

Beberapa sertifikat dalam konfigurasi

Rotasi otomatis dengan Azure Key Vault

Memecahkan masalah kesalahan sertifikat

Kesalahan umum

Sertifikat tidak ditemukan

Akses ditolak ke Key Vault

Kunci privat sertifikat tidak dapat diakses

Sertifikat kedaluwarsa

Kata sandi sertifikat salah

Daftar periksa diagnostik

Aktifkan pengelogan

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: