Microsoft.Identity.Web için kimlik bilgilerine genel bakış

Uygulamanız Microsoft kimlik platformu kimlik doğrulaması yaparken kimliğini kanıtlamak için bir kimlik bilgisi sunar. Microsoft. Identity.Web, her biri farklı ortamlara ve güvenlik gereksinimlerine uygun çeşitli kimlik bilgisi türlerini destekler.

Bu makale, kullanılabilir kimlik bilgisi türlerini anlamanıza, senaryonuz için doğru kimlik bilgilerini seçmenize ve uygulamanızda kimlik bilgilerini yapılandırmanıza yardımcı olur.

Kimlik bilgisi seçimi neden önemlidir?

Uygulamanızın kullandığı kimlik bilgileri güvenlik duruşunu, işletimsel ek yükünü ve dağıtım esnekliğini doğrudan etkiler. Kötü seçilmiş bir kimlik bilgisi sırları açığa çıkarabilir, manuel döndürme gerektirebilir veya uygulamanızın çalışabileceği yeri sınırlayabilir.

Microsoft. Identity.Web şunları yapmanızı sağlayan birleşik bir yapılandırma modeli sağlar:

  • Otomatik geri dönüş ile birden çok kimlik bilgisi belirtin.
  • Uygulama kodunu değiştirmeden kimlik bilgisi türlerini değiştirin.
  • Ortam başına farklı kimlik bilgileri kullanın (geliştirme, hazırlama, üretim).

Desteklenen kimlik bilgisi türleri

Microsoft. Identity.Web, gizli istemci uygulamaları için üç kimlik bilgisi kategorisini destekler:

Sertifikasız kimlik bilgileri (Federasyon Kimliği kimlik bilgileri + Yönetilen Kimlik)

Sertifikasız kimlik doğrulaması, uygulamanızın kimliğini doğrulamak için gizli bilgiler veya sertifikalarla uğraşmadan Azure Yönetilen Kimlik ile Federasyon Kimliği Kimlik Bilgilerini (FIC) kullanır. Azure kimlik bilgisi yaşam döngüsünü tamamen işler.

Nasıl çalışır: Uygulamanız, Microsoft kimlik platformuunun önceden yapılandırılmış federasyon güveni aracılığıyla uygulamanın kimliğinin kanıtı olarak kabul ettiği bir belirteç elde etmek için yönetilen kimliğini kullanır.

En uygun: Azure üzerinde çalışan üretim iş yükleri için.

Sertifikasız kimlik doğrulaması hakkında daha fazla bilgi edinin

Certificates

Sertifikalar güçlü, asimetrik anahtar tabanlı kimlik doğrulaması sağlar. Uygulamanız, sertifikanın özel anahtarıyla bir onay imzalayarak kimliğini kanıtlar. Microsoft. Identity.Web birden çok kaynaktan sertifika yükleyebilir:

  • Azure Key Vault - Erişim ilkeleriyle merkezi, yönetilen sertifika depolama alanı.
  • Certificate Store - Windows sertifika deposu (CurrentUser veya LocalMachine).
  • Dosya yolu - Disk üzerindeki sertifika dosyası (.pfx biçimi).
  • Base64 ile kodlanmış - Doğrudan yapılandırmaya eklenmiş sertifika.

En uygun olan: Sertifikasız kimlik bilgilerinin kullanılamadığı üretim iş yükleri veya karma çalışma ortamları.

Sertifika kimlik bilgileri hakkında daha fazla bilgi edinin

İstemci gizli anahtarları

İstemci gizli kodları, uygulamanızın Microsoft kimlik platformuna sunduğu paylaşılan kodlardır. Bunlar, yapılandırılan en basit kimlik bilgisi türüdür ancak en zayıf güvenliği sunar.

En iyisi: Yalnızca yerel geliştirme ve test içindir.

İstemci gizli anahtarları hakkında daha fazla bilgi edinin

Doğru kimlik bilgisi türünü seçin

Senaryonuza uygun kimlik bilgisi türünü belirlemek için aşağıdaki karar ağacını kullanın.

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

Genel kılavuz

Bir kimlik bilgisi türü seçerken şu ilkeleri izleyin:

  • Uygulamanız Azure üzerinde çalışırken her zaman sertifikasız kimlik bilgilerini tercih edin. Kimlik bilgisi yönetimini tamamen ortadan kaldırır.
  • Sertifikasız kimlik bilgileri kullanılamadığında sertifikaları kullanın. Mümkün olduğunca Azure Key Vault depolayın.
  • İstemci gizli anahtarlarını geliştirme ortamlarıyla kısıtla. Üretim dağıtımlarında hiçbir zaman istemci sırları kullanmayın.

Kimlik bilgisi türlerini karşılaştırma

Aşağıdaki tabloda, kimlik bilgisi türleri arasındaki temel farklar özetlenmiştir:

Characteristic Sertifikasız (FIC + MI) Certificates İstemci gizli anahtarları
Güvenlik düzeyi En Yüksek Yüksek Low
Gizli açığa çıkarma riski Hiçbiri - sızdıracak gizli bilgi yok Düşük - özel anahtar korumalı Yüksek - dize kopyalanabilir
Döndürme gerekli Hayır - yaşam döngüsünü Azure yönetir Evet - sertifikanın süresi dolmadan önce Evet - gizli son kullanma tarihi öncesi
Döndürme karmaşıklığı Hiçbiri Orta - sertifikayı güncelleştirme, yeniden dağıtma Düşük - güncelleştirme dizesi, yeniden dağıtma
Azure portal kurulumu Yönetilen Kimlik + FIC Güvenilirliği Uygulama kaydına sertifika yükleme Uygulama kaydında gizli anahtar oluşturma
Uygun ortamlar Azure üretimi Herhangi bir üretim ortamı Yalnızca geliştirme ve test
Altyapı bağımlılığı Azure işlem kaynağı Sertifika deposu veya Key Vault Hiçbiri
Uyumluluk Sıfır güven gereksinimlerini karşılar Uyumluluk çerçevelerinin çoğunu karşılar Güvenlik ilkelerini karşılamayabilir

appsettings.json kimlik bilgilerini yapılandırma

Microsoft. Identity.Web, yapılandırmanızda bir veya daha fazla kimlik bilgisi belirtmek için bir ClientCredentials dizisi kullanır. Dizideki her giriş, kimlik bilgilerinin nereden geldiğini gösteren bir SourceType özellik içerir.

Yapılandırma yapısı

Aşağıdaki örnekte tek bir sertifikasız kimlik bilgileriyle minimum yapılandırma gösterilmektedir:

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

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

SourceType değerleri

SourceType özelliği CredentialSource numaralandırmasına karşılık gelir ve Microsoft.Identity.Web'in kimlik bilgilerini nasıl yüklediğini belirler.

SourceType değeri Kimlik bilgisi türü Açıklama
SignedAssertionFromManagedIdentity Sertifikasız İmzalı bir beyan almak için yönetilen kimliği kullanır. Azure üretim ortamı için önerilir.
KeyVault Certificate Azure Key Vault'tan bir sertifikayı URI üzerinden yükler.
StoreWithThumbprint Certificate parmak iziyle Windows sertifika deposundan bir sertifika yükler.
StoreWithDistinguishedName Certificate Windows sertifika deposundan konu ayırt edici adına göre bir sertifika yükler.
Path Certificate Disk üzerindeki bir .pfx dosyasından sertifika yükler.
Base64Encoded Certificate Yapılandırmada Base64 ile kodlanmış bir dizeden sertifika yükler.
ClientSecret İstemci gizliliği Müşteri sır dizisini kullanıyor.
AutoDecryptKeys Jeton şifre çözümü Şifrelenmiş belirteçlerin şifresini çözmek için anahtarları otomatik olarak alır.
SignedAssertionFilePath Federatif Bir dosya yolundan imzalı bir beyan okur (Kubernetes iş yükü kimliği için).

Türe göre kimlik bilgileri örnekleri

Aşağıdaki örneklerde, C# kodunda appsettings.json ve varsa her kimlik bilgisi türünün nasıl yapılandırıldığı gösterilmektedir.

Sertifikasız (yönetilen kimlik)

İstemci kimliğini belirterek kullanıcı tarafından atanan yönetilen kimliği kullanın:

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

Sistem tarafından atanan yönetilen kimlik için ManagedIdentityClientId özelliğini atlayın.

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

Azure Key Vault sertifikası

Kasa URL'sini ve sertifika adını belirterek Azure Key Vault'de depolanan bir sertifikayı yükleyin:

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

C# dilinde yardımcı yöntemini de kullanabilirsiniz CredentialDescription :

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

Sertifika deposundan sertifika

parmak iziyle Windows sertifika deposundan bir sertifika yükleyin:

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

Ayrıca, yeni sertifika otomatik olarak seçildiğinden sertifika döndürmeyi basitleştiren ayırt edici bir ad da kullanabilirsiniz:

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

C# dilinde yardımcı yöntemini kullanın:

// 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");

Dosya yolundan alınan sertifika

Disk üzerindeki bir .pfx dosyadan sertifika yükleyin:

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

Uyarı

Sertifika parolalarını doğrudan içinde appsettings.jsondepolamaktan kaçının. Hassas değerler için ASP.NET Core Gizli Dizi Yöneticisi, ortam değişkenleri veya Azure Key Vault kullanın.

Base64 ile kodlanmış sertifika

Sertifikayı doğrudan yapılandırmaya Base64 kodlu dize olarak ekleyin:

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

İstemci gizliliği

Geliştirme ve test için bir istemci gizli dizisi belirtin:

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

Dikkat

İstemci sırları yalnızca geliştirme aşamasında kullanılmalıdır. Gizli bilgileri asla kaynak denetimine kaydetmeyin veya üretim ortamlarına yerleştirmeyin.

Geri dönüş ile birden çok kimlik bilgisi kullanma

Dizide ClientCredentials birden çok kimlik bilgisi belirtebilirsiniz. Microsoft. Identity.Web her kimlik bilgilerini sırayla dener ve geçerli kimlik bilgisi başarısız olursa bir sonrakine geri döner. Bu desen, birden çok ortamda çalışan uygulamalar için kullanışlıdır.

{
  "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"
      }
    ]
  }
}

Bu örnekte:

  1. Uygulama ilk olarak yönetilen kimlikle sertifikasız kimlik doğrulaması dener (Azure üzerinde çalışır).
  2. Yönetilen kimlik kullanılamıyorsa, bir sertifika için Key Vault'a geri dönülür.
  3. Son çare olarak, bir istemci sırrı kullanır (yerel geliştirme için).

Bu yaklaşım, kod değişikliği olmadan ortamlar arasında aynı yapılandırma dosyasını kullanmanıza olanak tanır.

Kodda kimlik bilgilerini yapılandırma

Kimlik bilgilerini program aracılığıyla Program.cs veya Startup.cs içinde de yapılandırabilirsiniz.

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"
        }
    };
});

Token şifre çözme kimlik bilgileri

Microsoft.Identity.Web, kimlik doğrulaması için istemci kimlik bilgilerinin yanı sıra, belirteç şifre çözme için de kimlik bilgilerini destekler. Uygulamanız şifrelenmiş belirteçler aldığında ve bunların şifresini çözmesi gerektiğinde belirteç şifre çözme kimlik bilgilerini kullanın.

Belirteç şifre çözme kimlik bilgileri, istemci kimlik bilgileriyle aynı SourceType değerleri ve yapılandırma desenlerini kullanır, ancak TokenDecryptionCredentials dizisinde belirtilir.

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

Token şifre çözme hakkında daha fazla bilgi edinin

En iyi uygulamalar

Uygulamanız için kimlik bilgilerini yapılandırırken şu önerileri göz önünde bulundurun:

Üretimde sertifikasız kimlik bilgilerini tercih edin. Gizli bilgi açığa çıkma riskini ortadan kaldırır ve döndürme işlemlerinin gereksiz yükünü azaltır. Uygulamanız yönetilen kimliği destekleyen Azure işlem kaynakları üzerinde her çalıştırıldığında bunları kullanın.

Taşınabilirlik için kimlik bilgisi geri dönüşünü kullanın. Uygulamanızın kod değişikliği olmadan geliştirme, hazırlama ve üretim genelinde çalışması için birden çok kimlik bilgilerini öncelik sırasına göre yapılandırın.

Üretimde asla istemci sırları kullanmayın. İstemci gizli bilgileri günlükler, yapılandırma dosyaları veya versiyon kontrolü aracılığıyla sızabilir. Bunun yerine sertifikaları veya sertifikasız kimlik bilgilerini kullanın.

Hassas değerleri yapılandırma dosyalarının dışında depolayın. Sertifika parolaları ve istemci gizli dizileri için Azure Key Vault, ortam değişkenlerini veya ASP.NET Core Gizli Dizi Yöneticisi'ni kullanın. Hassas değerleri kaynak denetimine işlemeyin.

Sertifikaları süresi dolmadan önce döndürün. Sertifika süre sonu tarihlerini izleyin ve döndürme işlemi oluşturun. Azure Key Vault sertifika yenilemeyi otomatikleştirebilir.

Sertifika depolama için Azure Key Vault kullanın. Key Vault, sertifikalar için merkezi yönetim, erişim ilkeleri, denetim günlüğü ve otomatik döndürme sağlar.

İlgili içerik

  • Last updated on