Gambaran umum kredensial untuk Microsoft. Identity.Web

Saat aplikasi Anda mengautentikasi dengan platform identitas Microsoft, aplikasi tersebut menyajikan kredensial untuk membuktikan identitasnya. Microsoft. Identity.Web mendukung beberapa jenis kredensial, masing-masing cocok untuk lingkungan dan persyaratan keamanan yang berbeda.

Artikel ini membantu Anda memahami jenis kredensial yang tersedia, memilih yang tepat untuk skenario Anda, dan mengonfigurasi kredensial di aplikasi Anda.

Mengapa pilihan kredensial penting

Kredensial yang digunakan aplikasi Anda secara langsung memengaruhi postur keamanan, overhead operasional, dan fleksibilitas penyebarannya. Kredensial yang dipilih dengan buruk dapat mengekspos rahasia, memerlukan rotasi manual, atau membatasi tempat aplikasi Anda dapat berjalan.

Microsoft. Identity.Web menyediakan model konfigurasi terpadu yang memungkinkan Anda:

  • Tentukan beberapa kredensial dengan fallback otomatis.
  • Ubah jenis kredensial tanpa memodifikasi kode aplikasi.
  • Gunakan kredensial yang berbeda per lingkungan (pengembangan, penahapan, produksi).

Jenis kredensial yang didukung

Microsoft. Identity.Web mendukung tiga kategori kredensial untuk aplikasi klien rahasia:

Kredensial tanpa sertifikat (Kredensial Identitas Federasi + Identitas Terkelola)

Kredensial tanpa sertifikat menggunakan identitas terkelola Azure dikombinasikan dengan Federated Identity Credentials (FIC) untuk mengautentikasi aplikasi Anda tanpa mengelola rahasia atau sertifikat apa pun. Azure menangani siklus hidup kredensial sepenuhnya.

Bagaimana cara kerjanya: Aplikasi Anda menggunakan identitas terkelolanya untuk mendapatkan token, yang diterima platform identitas Microsoft sebagai bukti identitas aplikasi melalui kepercayaan federasi yang telah dikonfigurasi sebelumnya.

Terbaik untuk: beban kerja produksi yang berjalan di Azure.

Pelajari selengkapnya tentang autentikasi tanpa sertifikat

Certificates

Sertifikat menyediakan autentikasi berbasis kunci asimetris yang kuat. Aplikasi Anda membuktikan identitasnya dengan menandatangani pernyataan dengan kunci privat sertifikat. Microsoft. Identity.Web dapat memuat sertifikat dari beberapa sumber:

  • Azure Key Vault - Penyimpanan sertifikat terpusat dan terkelola dengan kebijakan akses.
  • Certificate Store - penyimpanan sertifikat Windows (CurrentUser atau LocalMachine).
  • Jalur file - File sertifikat pada disk (format.pfx).
  • Dikodekan Base64 - Sertifikat yang disematkan langsung dalam konfigurasi.

Terbaik untuk: Beban kerja produksi di mana kredensial tanpa sertifikat tidak tersedia, atau lingkungan hibrid.

Pelajari selengkapnya tentang kredensial sertifikat

Rahasia klien

Rahasia klien adalah string yang dibagikan yang disampaikan oleh aplikasi Anda ke platform identitas Microsoft. Ini adalah jenis kredensial paling sederhana untuk dikonfigurasi tetapi menawarkan keamanan terlemah.

Terbaik untuk: Pengembangan dan pengujian lokal saja.

Pelajari selengkapnya tentang rahasia klien

Pilih jenis kredensial yang tepat

Gunakan pohon keputusan berikut untuk menentukan jenis kredensial mana yang sesuai untuk skenario Anda.

Is your application running on Azure?
├── Yes
│   ├── Can you use Managed Identity?
│   │   ├── Yes → Use certificateless credentials (recommended)
│   │   └── No → Use certificates from Azure Key Vault
└── No
    ├── Is this a production environment?
    │   ├── Yes → Use certificates (Key Vault, Certificate Store, or file path)
    │   └── No → Use client secrets for development/testing

Panduan umum

Ikuti prinsip-prinsip ini saat memilih jenis kredensial:

  • Always lebih memilih kredensial tanpa sertifikat saat aplikasi Anda berjalan pada Azure. Mereka menghilangkan manajemen kredensial sepenuhnya.
  • Gunakan sertifikat saat kredensial tanpa sertifikat tidak tersedia. Simpan di Azure Key Vault jika memungkinkan.
  • Membatasi rahasia klien untuk lingkungan pengembangan. Jangan pernah menggunakan kunci rahasia klien dalam implementasi produksi.

Membandingkan jenis kredensial

Tabel berikut ini meringkas perbedaan utama antara jenis kredensial:

Karakteristik Tanpa sertifikat (FIC + MI) Certificates Rahasia klien
Tingkat keamanan Tertinggi Tinggi Kurang Penting
Risiko bocoran rahasia Tidak ada - tidak ada rahasia yang bocor Tingkat Rendah - perlindungan kunci privat Tinggi - teks dapat disalin
Rotasi diperlukan Tidak - Azure mengelola siklus hidup Ya - sebelum sertifikat kedaluwarsa Ya - sebelum kedaluwarsa rahasia
Kompleksitas rotasi Tidak Medium - perbarui sertifikat, deploy ulang Rendah - perbarui string, terapkan ulang
Penyiapan portal Azure Identitas Terkelola + kepercayaan FIC Mengunggah sertifikat ke pendaftaran aplikasi Membuat rahasia dalam pendaftaran aplikasi
Lingkungan yang sesuai Produksi Azure Lingkungan produksi apa pun Pengembangan dan pengujian saja
Dependensi infrastruktur Azure sumber daya komputasi Penyimpanan sertifikat atau Key Vault Tidak
Kepatuhan Memenuhi persyaratan kepercayaan nol Memenuhi sebagian besar kerangka kerja kepatuhan Mungkin tidak memenuhi kebijakan keamanan

Mengonfigurasi kredensial di appsettings.json

Microsoft. Identity.Web menggunakan array ClientCredentials dalam konfigurasi Anda untuk menentukan satu atau beberapa kredensial. Setiap entri dalam array menyertakan SourceType properti yang menunjukkan dari mana kredensial berasal.

Struktur konfigurasi

Contoh berikut menunjukkan konfigurasi minimal dengan satu kredensial tanpa sertifikat:

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

    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Nilai SourceType

Properti SourceType sesuai dengan enum CredentialSource dan menentukan bagaimana Microsoft.Identity.Web memuat kredensial.

Jenis Sumber nilai Jenis kredensial Deskripsi
SignedAssertionFromManagedIdentity Tanpa sertifikat Menggunakan identitas terkelola untuk mendapatkan pernyataan yang ditandatangani. Direkomendasikan untuk lingkungan produksi di Azure.
KeyVault Sertifikat Memuat sertifikat dari Azure Key Vault dengan menggunakan URI.
StoreWithThumbprint Sertifikat Memuat sertifikat dari penyimpanan sertifikat Windows dengan sidik jari digital.
StoreWithDistinguishedName Sertifikat Memuat sertifikat dari penyimpanan sertifikat Windows berdasarkan nama unik subjek.
Path Sertifikat Memuat sertifikat dari file .pfx pada disk.
Base64Encoded Sertifikat Memuat sertifikat dari string yang dikodekan Base64 dalam konfigurasi.
ClientSecret Rahasia klien Menggunakan string rahasia klien.
AutoDecryptKeys Dekripsi token Secara otomatis mengambil kunci untuk mendekripsi token terenkripsi.
SignedAssertionFilePath Tergabung Membaca pernyataan yang ditandatangani dari path file (untuk identitas beban kerja Kubernetes).

Contoh kredensial menurut jenis

Contoh berikut menunjukkan cara mengonfigurasi setiap jenis kredensial di appsettings.json dan, jika tersedia, dalam kode C#.

Tanpa sertifikat (identitas terkelola)

Gunakan identitas terkelola yang ditetapkan pengguna dengan menentukan ID kliennya:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Untuk identitas terkelola yang ditetapkan sistem, abaikan properti ManagedIdentityClientId

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  }
}

Sertifikat dari Azure Key Vault

Muat sertifikat yang disimpan di Azure Key Vault dengan menentukan URL vault dan nama sertifikat:

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

Anda juga dapat menggunakan metode pembantu CredentialDescription di C#:

var credential = CredentialDescription.FromKeyVault(
    "https://your-keyvault.vault.azure.net",
    "your-certificate-name");

Sertifikat dari toko sertifikat

Muat sebuah sertifikat dari penyimpanan sertifikat Windows menggunakan thumbprint:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateThumbprint": "ABC123DEF456...",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

Anda juga dapat menggunakan nama khusus, yang menyederhanakan rotasi sertifikat karena sertifikat baru dipilih secara otomatis:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateDistinguishedName": "CN=YourAppCertificate",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

Di C#, gunakan metode pembantu:

// By thumbprint
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "ABC123DEF456...");

// By distinguished name (recommended for rotation)
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=YourAppCertificate");

Sertifikat dari lokasi berkas

Muat sertifikat dari .pfx file pada disk:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/var/certs/app-cert.pfx",
        "CertificatePassword": "certificate-password"
      }
    ]
  }
}

Peringatan

Hindari menyimpan kata sandi sertifikat langsung di appsettings.json. Gunakan ASP.NET Core Secret Manager, variabel lingkungan, atau Azure Key Vault untuk nilai sensitif.

Sertifikat yang dikodekan Base64

Sematkan sertifikat langsung dalam konfigurasi sebagai string yang dikodekan Base64:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0..."
      }
    ]
  }
}

Rahasia klien

Tentukan string rahasia klien untuk pengembangan dan pengujian:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Perhatian

Rahasia klien hanya boleh digunakan selama pengembangan. Jangan pernah menerapkan rahasia untuk kontrol sumber atau menyebarkannya ke lingkungan produksi.

Menggunakan beberapa kredensial dengan cadangan

Anda dapat menentukan beberapa kredensial dalam ClientCredentials array. Microsoft. Identity.Web mencoba setiap kredensial secara berurutan dan kembali ke yang berikutnya jika kredensial saat ini gagal. Pola ini berguna untuk aplikasi yang berjalan di beberapa lingkungan.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "your-managed-identity-client-id"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      },
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "development-only-secret"
      }
    ]
  }
}

Dalam contoh ini:

  1. Aplikasi pertama kali mencoba autentikasi tanpa sertifikat dengan identitas terkelola (berfungsi pada Azure).
  2. Jika identitas terkelola tidak tersedia, identitas tersebut akan kembali ke sertifikat dari Key Vault.
  3. Sebagai upaya terakhir, ia menggunakan rahasia klien (untuk pengembangan lokal).

Pendekatan ini memungkinkan Anda menggunakan file konfigurasi yang sama di seluruh lingkungan tanpa perubahan kode.

Mengonfigurasi kredensial dalam kode

Anda juga dapat mengonfigurasi kredensial secara terprogram di Program.cs atau Startup.cs:

using Microsoft.Identity.Web;

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", builder.Configuration.GetSection("MyApi"))
    .AddDistributedTokenCaches();

// Or configure credentials programmatically
builder.Services.Configure<MicrosoftIdentityOptions>(options =>
{
    options.ClientCredentials = new[]
    {
        new CredentialDescription
        {
            SourceType = CredentialSource.SignedAssertionFromManagedIdentity,
            ManagedIdentityClientId = "your-managed-identity-client-id"
        }
    };
});

Kredensial dekripsi token

Di luar kredensial klien untuk autentikasi, Microsoft. Identity.Web juga mendukung kredensial untuk dekripsi token. Gunakan kredensial dekripsi token saat aplikasi Anda menerima token terenkripsi dan perlu mendekripsinya.

Kredensial dekripsi token menggunakan nilai dan pola konfigurasi yang sama SourceType dengan kredensial klien, tetapi ditentukan dalam TokenDecryptionCredentials array:

{
  "AzureAd": {
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "token-decryption-cert"
      }
    ]
  }
}

Pelajari selengkapnya tentang dekripsi token

Praktik terbaik

Ingatlah rekomendasi ini saat mengonfigurasi kredensial untuk aplikasi Anda:

Utamakan kredensial tanpa sertifikat dalam produksi. Mereka menghilangkan risiko paparan rahasia dan menghapus biaya manajemen rotasi. Gunakan setiap kali aplikasi Anda berjalan pada sumber daya komputasi Azure yang mendukung identitas terkelola.

Gunakan kredensial cadangan untuk portabilitas. Konfigurasikan beberapa kredensial dalam urutan prioritas sehingga aplikasi Anda berfungsi di seluruh pengembangan, penahapan, dan produksi tanpa perubahan kode.

Jangan pernah menggunakan rahasia klien dalam produksi. Rahasia klien dapat bocor melalui log, file konfigurasi, atau kontrol sumber. Gunakan sertifikat atau kredensial tanpa sertifikat sebagai gantinya.

Simpan nilai sensitif di luar file konfigurasi. Gunakan Azure Key Vault, variabel lingkungan, atau ASP.NET Core Secret Manager untuk kata sandi sertifikat dan rahasia klien. Jangan menerapkan nilai sensitif ke kontrol sumber.

Perbarui sertifikat sebelum kedaluwarsa. Pantau tanggal kedaluwarsa sertifikat dan buat proses rotasi. Azure Key Vault dapat mengotomatiskan perpanjangan sertifikat.

Gunakan Azure Key Vault untuk penyimpanan sertifikat. Key Vault menyediakan manajemen terpusat, kebijakan akses, pengelogan audit, dan rotasi otomatis untuk sertifikat.

Konten terkait

  • Last updated on