Gunakan rahasia klien dengan Microsoft. Identity.Web

Rahasia klien adalah nilai string yang digunakan aplikasi Anda untuk membuktikan identitasnya saat meminta token dari platform identitas Microsoft. Microsoft. Identity.Web mendukung rahasia klien sebagai salah satu dari beberapa jenis kredensial untuk aplikasi klien rahasia.

Pilih jenis kredensial

Aplikasi klien rahasia memerlukan kredensial untuk mengautentikasi dengan platform identitas Microsoft. Microsoft. Identity.Web mendukung jenis kredensial berikut melalui bagian konfigurasi ClientCredentials:

Rahasia klien adalah string sederhana yang terdaftar di aplikasi Anda di Microsoft Entra ID. Meskipun merupakan jenis kredensial yang paling mudah untuk disiapkan, mereka juga memiliki batasan keamanan yang signifikan:

• Mereka dapat secara tidak sengaja diekspos dalam kode sumber, log, atau file konfigurasi.
• Mereka memiliki tanggal kedaluwarsa dan harus diputar secara manual.
• Mereka tidak memberikan bukti kriptografi atas identitas penelepon selain kepemilikan rahasia.

Mengonfigurasi rahasia klien di appsettings.json

Untuk mengonfigurasi rahasia klien, tambahkan ClientCredentials array ke bagian AzureAd pada file appsettings.json Anda.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "YOUR_SECRET_VALUE"
      }
    ]
  }
}

Array ClientCredentials mendukung beberapa entri. Microsoft. Identity.Web mencoba setiap kredensial secara berurutan hingga berhasil, yang berguna untuk skenario rotasi rahasia.

Menyimpan rahasia untuk pengembangan

Bagian ini menjelaskan cara menyimpan nilai rahasia dari kode sumber Anda selama pengembangan lokal.

.NET rahasia pengguna

Pendekatan yang direkomendasikan untuk menyimpan rahasia selama pengembangan lokal adalah alat Secret Manager. Rahasia Pengguna menyimpan data sensitif di luar pohon proyek Anda, yang mencegah penerapan yang tidak disengaja ke kontrol sumber.

1. Inisialisasi Rahasia Pengguna untuk proyek Anda:

   dotnet user-secrets init
   

2. Atur nilai rahasia klien:

   dotnet user-secrets set "AzureAd:ClientCredentials:0:ClientSecret" "your-secret-value"
   

3. Verifikasi bahwa rahasia telah disimpan:

   dotnet user-secrets list
   

Rahasia Pengguna secara otomatis dimuat di Development lingkungan saat Anda menggunakan WebApplication.CreateBuilder() atau Host.CreateDefaultBuilder().

Anda appsettings.json harus berisi struktur tanpa nilai rahasia aktual:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret"
      }
    ]
  }
}

Variabel lingkungan

Anda juga dapat menggunakan variabel lingkungan untuk memberikan rahasia klien. konfigurasi .NET secara otomatis memetakan variabel lingkungan yang menggunakan pemisah __ (garis bawah ganda) ke hierarki konfigurasi. Atur variabel untuk shell Anda:

$env:AzureAd__ClientCredentials__0__ClientSecret = "your-secret-value"

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

Variabel lingkungan lebih diutamakan daripada nilai dalam appsettings.json, sehingga nilai rahasia dalam file konfigurasi Anda dapat kosong atau dihilangkan.

Menyimpan rahasia untuk lingkungan yang lebih tinggi

Untuk penahapan, QA, atau lingkungan bersama apa pun, gunakan Azure Key Vault sebagai sumber konfigurasi. Pendekatan ini menjaga rahasia dari file konfigurasi dan variabel lingkungan sambil menyediakan audit, kebijakan akses, dan kemampuan rotasi otomatis.

Menambahkan Azure Key Vault sebagai sumber konfigurasi

1. Instal paket NuGet yang diperlukan:

   dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets
   

2. Simpan secret client di Azure Key Vault dengan nama yang sesuai dengan jalur konfigurasi. Gunakan -- (garis putus ganda) sebagai pemisah:

   az keyvault secret set \
     --vault-name "your-keyvault-name" \
     --name "AzureAd--ClientCredentials--0--ClientSecret" \
     --value "your-secret-value"
   

3. Tambahkan Key Vault sebagai sumber konfigurasi di Program.cs. Kode berikut mendaftarkan Key Vault sehingga rahasianya tersedia melalui API konfigurasi standar:

   var builder = WebApplication.CreateBuilder(args);
   
   builder.Configuration.AddAzureKeyVault(
       new Uri("https://your-keyvault-name.vault.azure.net/"),
       new DefaultAzureCredential());
   

Nama rahasia di Key Vault AzureAd--ClientCredentials--0--ClientSecret dipetakan secara otomatis ke jalur konfigurasi AzureAd:ClientCredentials:0:ClientSecret.

Membuat rahasia klien di portal Azure

Ikuti langkah-langkah ini untuk mendaftarkan rahasia klien untuk aplikasi Anda di Microsoft Entra ID:

1. Masuk ke pusat admin Microsoft Entra.
2. Navigasi ke Identity>Aplikasi>Registrasi Aplikasi.
3. Pilih aplikasi Anda dari daftar.
4. Di menu sebelah kiri, pilih Sertifikat & rahasia.
5. Pilih tab Rahasia klien .
6. Pilih Rahasia klien baru.
7. Di panel Tambahkan rahasia klien :
   • Masukkan Deskripsi untuk rahasia (misalnya, "Rahasia pengembangan").
   • Pilih durasi Kedaluwarsa . Opsi yang tersedia termasuk 180 hari, 365 hari, 730 hari, atau tanggal kustom.
   • Pilih Tambahkan.
8. Salin nilai rahasia segera. Nilai hanya ditampilkan sekali dan tidak dapat diambil setelah Anda menavigasi jauh dari halaman.

Mengelola kedaluwarsa dan rotasi rahasia

Rahasia klien memiliki masa pakai maksimum dan kedaluwarsa pada tanggal yang ditentukan selama pembuatan. Rencanakan rotasi rahasia untuk menghindari pemadaman aplikasi.

Pantau kedaluwarsa

• Periksa kolom Kedaluwarsa di halaman Sertifikat & rahasia pendaftaran aplikasi Anda.
• Siapkan rekomendasi Microsoft Entra untuk menerima pemberitahuan sebelum kredensial kedaluwarsa.

Strategi rotasi

Gunakan array ClientCredentials untuk mendukung rotasi tanpa waktu henti.

1. Buat rahasia klien baru di portal Azure.

2. Tambahkan rahasia baru sebagai entri tambahan dalam ClientCredentials array. Tempatkan rahasia baru terlebih dahulu sehingga dicoba sebelum yang lama:

   {
     "AzureAd": {
       "ClientCredentials": [
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[NEW_SECRET_REFERENCE]"
         },
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[OLD_SECRET_REFERENCE]"
         }
       ]
     }
   }
   

3. Sebarkan konfigurasi yang diperbarui. Microsoft. Identity.Web mencoba kredensial pertama dan kembali ke yang kedua jika yang pertama gagal.

4. Setelah mengonfirmasi rahasia baru berfungsi, hapus rahasia lama dari konfigurasi dan portal Azure.

Pindah ke kredensial produksi

Sebelum menyebarkan ke produksi, migrasikan dari rahasia klien ke jenis kredensial yang lebih aman:

Autentikasi berbasis sertifikat

Sertifikat memberikan bukti kriptografi identitas dan merupakan jenis kredensial yang direkomendasikan untuk produksi. Konfigurasi berikut mengambil sertifikat dari Key Vault:

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

Untuk langkah-langkah terperinci, lihat Gunakan sertifikat dengan Microsoft. Identity.Web.

Identitas yang dikelola (bebas sertifikat)

Untuk aplikasi yang dihosting di Azure, identitas terkelola menghilangkan kebutuhan untuk mengelola kredensial sepenuhnya. Konfigurasi berikut menggunakan identitas terkelola yang ditetapkan pengguna:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "YOUR_MANAGED_IDENTITY_CLIENT_ID"
      }
    ]
  }
}

Untuk langkah-langkah terperinci, silakan lihat autentikasi tanpa sertifikat dengan Microsoft.Identity.Web.

Daftar periksa migrasi

• [ ] Hasilkan atau provisikan kredensial baru (sertifikat atau identitas terkelola).
• [ ] Perbarui konfigurasi aplikasi Anda untuk menggunakan jenis kredensial baru.
• [ ] Uji kredensial baru di lingkungan uji coba.
• [ ] Sebarkan ke lingkungan produksi.
• [ ] Hapus rahasia klien lama dari portal Azure.
• [ ] Verifikasi fungsi aplikasi dengan benar tanpa rahasia lama.

Hindari kesalahan keamanan umum

Tinjau pola buruk berikut dan alternatif yang direkomendasikan saat bekerja dengan rahasia pelanggan:

Memecahkan masalah kesalahan umum

Bagian ini mencakup kesalahan yang sering Anda temui saat mengonfigurasi rahasia klien.

Rahasia klien tidak valid

Kesalahan:AADSTS7000215: Invalid client secret provided.

Kemungkinan penyebabnya:

• Nilai rahasia salah disalin. Nilai rahasia dapat berisi karakter khusus yang dipotong selama operasi salin/tempel.
• Rahasia dibuat untuk pendaftaran aplikasi yang berbeda dari yang dikonfigurasi di ClientId.
• Jalur konfigurasi salah, dan nilai rahasia tidak dibaca oleh aplikasi.

Resolusi:

1. Buat rahasia klien baru di portal Azure dan salin nilai lengkap dengan hati-hati.

2. Verifikasi ClientId dan TenantId dalam konfigurasi Anda sesuai dengan pendaftaran aplikasi di mana kunci rahasia dibuat.

3. Tambahkan titik henti atau pernyataan log untuk memverifikasi konfigurasi dimuat dengan benar:

   // For debugging only — remove before committing
   var config = builder.Configuration.GetSection("AzureAd:ClientCredentials:0:ClientSecret").Value;
   Console.WriteLine($"Secret loaded: {!string.IsNullOrEmpty(config)}");
   

Rahasia klien kedaluwarsa

Kesalahan:AADSTS7000222: The provided client secret keys for app '{app-id}' are expired.

Resolusi:

1. Navigasi ke pendaftaran aplikasi di pusat admin Microsoft Entra.
2. Periksa tanggal kedaluwarsa di bawah Sertifikat & rahasia>Rahasia klien.
3. Buat rahasia baru dan perbarui konfigurasi aplikasi Anda.
4. Hapus rahasia yang kedaluwarsa dari portal.

Rahasia tidak ditemukan dalam konfigurasi

Gejala: Aplikasi melempar NullReferenceException atau gagal mengautentikasi karena nilai rahasianya adalah null.

Kemungkinan penyebabnya:

• Rahasia Pengguna tidak diinisialisasi untuk proyek.
• Nama variabel lingkungan tidak cocok dengan jalur konfigurasi yang diharapkan.
• Key Vault tidak dikonfigurasi sebagai sumber konfigurasi.
• Aplikasi ini berjalan di lingkungan non-Pengembangan tempat Rahasia Pengguna tidak dimuat.

Resolusi:

1. Memastikan Rahasia Pengguna sudah diinisialisasi dengan memeriksa UserSecretsId di file .csproj Anda.
2. Verifikasi rahasia diatur dengan menjalankan dotnet user-secrets list.
3. Periksa apakah jalur konfigurasi cocok persis: AzureAd:ClientCredentials:0:ClientSecret.
4. Jika berjalan di luar lingkungan Pengembangan, pastikan sumber konfigurasi yang sesuai (variabel lingkungan atau Key Vault) tersedia.

Konten terkait

• Certificates dengan Microsoft.Identity.Web
• Autentikasi tanpa sertifikat
• Gambaran umum tentang cache token
• penyimpanan rahasia aplikasi yang aman dalam pengembangan di ASP.NET Core
• Penyedia konfigurasi untuk Azure Key Vault dalam ASP.NET Core