Microsoft.Identity.Web ile istemci gizliliklerini kullanın

İstemci gizli anahtarı, uygulamanızın Microsoft kimlik platformu belirteçleri istediğinde kimliğini kanıtlamak için kullandığı bir dize değeridir. Microsoft.Identity.Web, gizli müşteri uygulamaları için çeşitli kimlik bilgisi türlerinden biri olarak istemci sırlarını destekler.

Önemli

İstemci gizli anahtarları yalnızca geliştirme ve test ortamlarında kullanılmalıdır. Üretim iş yükleri için sertifikaları veya yönetilen kimlikler veya federasyon kimlik bilgileri gibi sertifikasız kimlik bilgilerini kullanın. İstemci gizli bilgilerinin tehlikeye atılması, sertifika tabanlı kimlik bilgilerine göre daha kolaydır ve belirli işlemlerle sınırlandırılamaz.

Bir kimlik bilgisi türü seçin

Microsoft kimlik platformunda kimlik doğrulaması için gizli istemci uygulamalarının bir kimlik bilgisine ihtiyacı vardır. Microsoft. Identity.Web, ClientCredentials yapılandırma bölümü aracılığıyla aşağıdaki kimlik bilgisi türlerini destekler:

Kimlik bilgisi türü Önerilen ortam Güvenlik düzeyi
İstemci sırrı Geliştirme, test etme Low
Sertifika Hazırlama, üretim Yüksek
Yönetilen kimlik Azure'da barındırılan üretim En Yüksek
Federasyon kimliği CI/CD, Kubernetes Yüksek

İstemci sırları, uygulamanızla Microsoft Entra ID'ye kaydedilen basit değerlerdir. Bunların ayarlanması en kolay kimlik bilgisi türü olsa da, önemli güvenlik sınırlamaları da vardır:

  • Bunlar yanlışlıkla kaynak kodunda, günlüklerde veya yapılandırma dosyalarında gösterilebilir.
  • Son kullanma tarihleri vardır ve el ile döndürülmeleri gerekir.
  • Çağrı yapıcının kimliği hakkında, sırrın sahibi olmaktan başka, kriptografik bir kanıt sağlamazlar.

appsettings.json dosyasında istemci sırrını yapılandırın

İstemci gizli anahtarını yapılandırmak için ClientCredentials dosyanızın AzureAd bölümüne bir appsettings.json dizi ekleyin:

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

Dizi ClientCredentials birden çok girdiyi destekler. Microsoft.Identity.Web, başarılı olana kadar her bir kimlik bilgisini sırayla dener ve bu da gizli anahtar döndürme senaryoları için yararlıdır.

Uyarı

Gerçek gizli değerleri hiçbir zaman kaynak denetimine işlemeyin. YOUR_SECRET_VALUE Yukarıdaki örnekteki yer tutucu, aşağıdaki bölümlerde açıklandığı gibi güvenli bir depoya referansla değiştirilmelidir.

Geliştirme için gizli bilgileri depolama

Bu bölümde, yerel geliştirme sırasında gizli değerlerin kaynak kodunuzun dışında nasıl tutulacağı açıklanmaktadır.

.NET kullanıcı gizli bilgileri

Yerel geliştirme sırasında gizli bilgileri depolamak için önerilen yaklaşım Gizli Bilgi Yöneticisi aracıdır. Kullanıcı Sırları, hassas verileri proje ağacınızın dışında depolar ve bu da kaynak denetimine yanlışlıkla taahhüt edilmesini önler.

  1. Projenizde Kullanıcı Gizli Verilerini başlatın.

    dotnet user-secrets init

  2. İstemci gizli anahtar değerini ayarlayın:

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

  3. Gizli bilginin depolandığını doğrulayın:

    dotnet user-secrets list

Development veya WebApplication.CreateBuilder() kullandığınızda, Kullanıcı Gizli Bilgileri Host.CreateDefaultBuilder() ortamına otomatik olarak yüklenir.

appsettings.json gerçekte gizli dizi değerini içermeden yapısını içermelidir.

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

Ortam değişkenleri

İstemci sırrını sağlamak için ortam değişkenlerini de kullanabilirsiniz. .NET yapılandırması, __ (çift alt çizgi) ayırıcısını kullanan ortam değişkenlerini otomatik olarak yapılandırma hiyerarşisine eşler. Kabuğunuz için değişkeni ayarlayın:

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

Ortam değişkenleri appsettings.json içindeki değerlerden önce gelir, bu nedenle yapılandırma dosyanızdaki gizli değer boş olabilir veya atlanabilir.

Üst ortamlar için gizli verileri depolayın

Hazırlama, Soru-Cevap veya herhangi bir paylaşılan ortam için yapılandırma kaynağı olarak Azure Key Vault kullanın. Bu yaklaşım, denetim, erişim politikaları ve otomatik dönüşüm özellikleri sağlarken yapılandırma dosyalarından ve ortam değişkenlerinden gizli bilgileri uzak tutar.

yapılandırma kaynağı olarak Azure Key Vault ekleme

  1. Gerekli NuGet paketini yükleyin:

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

  2. Azure Anahtar Kasası içerisinde, yapılandırma yoluna eşlenen bir adla istemci gizli anahtarını depolayın. Ayırıcı olarak (çift tire) -- kullanın:

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

  3. Program.cs'da yapılandırma kaynağı olarak Key Vault ekleyin. Key Vault'u kaydeden aşağıdaki kod, sırlarının standart yapılandırma API'si aracılığıyla kullanılabilir olmasını sağlar.

    var builder = WebApplication.CreateBuilder(args);

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

Key Vault gizli dizi adı AzureAd--ClientCredentials--0--ClientSecret otomatik olarak AzureAd:ClientCredentials:0:ClientSecret yapılandırma yoluna eşler.

Tip

Key Vault kullanarak istemci gizli bilgisini depolarken bile, üretim iş yükünüzün sertifikalarla veya yönetilen kimlik hizmetleriyle daha iyi çalışıp çalışmayacağını düşünün. Key Vault paylaşılan geliştirme veya hazırlama ortamları için yararlıdır, ancak üretim uygulamaları daha güçlü kimlik bilgileri türleri kullanmalıdır.

Azure portalında istemci gizli anahtarı oluşturma

Microsoft Entra ID'da uygulamanız için bir istemci sırrı kaydetmek üzere şu adımları izleyin:

  1. Microsoft Entra yönetim merkezinde oturum açın.
  2. Identity>Applications>Uygulama kayıtları adresine gidin.
  3. Listeden uygulamanızı seçin.
  4. Soldaki menüde Sertifikalar ve gizlilikler seçin.
  5. İstemci sırları sekmesini seçin.
  6. Yeni istemci gizli anahtarını seçin.
  7. İstemci parolası ekle bölmesinde:
    • Gizli için bir Açıklama girin (örneğin, "Geliştirme şifresi").
    • Sona Erme Süresi seçin. Kullanılabilir seçenekler arasında 180 gün, 365 gün, 730 gün veya özel bir tarih bulunur.
    • Add (Ekle) seçeneğini belirleyin.
  8. Gizli değeri hemen kopyalayın. Değer yalnızca bir kez gösterilir ve sayfadan uzaklaştıktan sonra alınamaz.

Önemli

Gizli değeri oluşturulduktan hemen sonra güvenli bir konuma kaydedin. Microsoft Entra ID yalnızca oluşturma zamanında değeri görüntüler. Değeri kaybederseniz yeni bir sır oluşturmanız gerekir.

Gizli anahtarların geçerlilik süresini ve yenilemeyi yönetme

İstemci sırları belirli bir süreye sahiptir ve oluşturma sırasında belirtilen tarihte sona erer. Uygulama kesintilerini önlemek için gizli dizi döndürmeyi planlayın.

Sürenin bitimini izleme

  • Uygulama kaydınızın Sertifikalar ve gizli diziler sayfasındaki Süre sonu sütununu işaretleyin.
  • Kimlik bilgilerinin süresi dolmadan önce uyarı almak için Microsoft Entra önerileri ayarlayın.

Döndürme stratejisi

Sıfır kesinti süresiyle döndürmeyi desteklemek için ClientCredentials dizisini kullanın.

  1. Azure portalında yeni bir istemci sırrı oluşturun.

  2. Yeni anahtarı ClientCredentials dizisine ek giriş olarak ekleyin. Eski sırdan önce denenebilmesi için yeni sırrı önce yerleştirin.

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

  3. Güncelleştirilmiş yapılandırmayı dağıtın. Microsoft. Identity.Web ilk kimlik bilgilerini dener ve ilk kimlik bilgisi başarısız olursa ikinciye geri döner.

  4. Yeni gizli anahtarın çalıştığını onayladıktan sonra, eski gizli anahtarı hem yapılandırmadan hem de Azure portalından kaldırın.

Üretim kimlik bilgilerine geçiş

Canlıya geçmeden önce, istemci sırlarından daha güvenli bir kimlik doğrulama türüne geçin.

Sertifika tabanlı kimlik doğrulaması

Sertifikalar kimlik şifreleme kanıtı sağlar ve üretim için önerilen kimlik bilgisi türüdür. Aşağıdaki yapılandırma, Key Vault'tan bir sertifika getirir:

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

Ayrıntılı adımlar için bkz. Microsoft.Identity.Web ile sertifikaları kullanma.

Yönetilen kimlik (sertifikasız)

Azure barındırılan uygulamalar için yönetilen kimlikler, kimlik bilgilerini tamamen yönetme gereksinimini ortadan kaldırır. Aşağıdaki yapılandırmada kullanıcı tarafından atanan yönetilen kimlik kullanılır:

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

Ayrıntılı adımlar için bkz. Microsoft.Identity.Web ile Sértisiz kimlik doğrulaması.

Geçiş denetim listesi

  • [ ] Yeni kimlik bilgilerini (sertifika veya yönetilen kimlik) oluşturun veya sağlayın.
  • [ ] Uygulama yapılandırmanızı yeni kimlik bilgisi türünü kullanacak şekilde güncelleştirin.
  • [ ] Hazırlama ortamında yeni kimlik bilgilerini test edin.
  • [ ] Üretim ortamına dağıtın.
  • [ ] Eski istemci gizli anahtarını Azure Portalı'ndan kaldırın.
  • [ ] Eski gizli anahtar olmadan uygulamanın düzgün çalıştığını doğrulayın.

Yaygın güvenlik hatalarından kaçının

İstemci gizli dizileriyle çalışırken aşağıdaki anti-desenleri ve bunların önerilen alternatiflerini gözden geçirin:

Desenden koruma Risk Tavsiye
Kaynak kodunda gizli anahtarları sabit kodlama Sürüm denetiminde açığa çıkan gizli information Kullanıcı Gizli Dizilerini, ortam değişkenlerini veya Key Vault kullanma
Gizli bilgilerle işleme appsettings.Development.json Gizli bilgiye depo erişimi olan herkes erişebilir. Dosyayı .gitignore öğesine ekleyin ve Kullanıcı Gizli Dizilerini kullanın
Ortamlar arasında gizli anahtarları paylaşımı Ele geçirilmiş geliştirme sırrı üretimi riske atar Ortam başına benzersiz gizli bilgileri kullanın
Üretimde gizli bilgileri kullanma Kimlik bilgisi hırsızlığı riski daha yüksek Sertifikalara veya yönetilen kimliklere geçiş
Süresi dolmayacak gizli bilgiler oluşturma Gizli anahtarın süresi dolduğunda uygulama kesintisi Süre sonu anımsatıcılarını ayarlama ve döndürmeyi uygulama
Gizli değerleri günlüğe kaydetme Günlük dosyalarında açığa çıkan gizli bilgi Kimlik bilgisi değerlerini hiçbir zaman günlüğe kaydetme; yalnızca kimlik bilgisi kaynağının türünü günlüğe kaydet.
Sunucularda gizli bilgileri metin dosyalarında depolama Sunucu erişimi olan herkes için ifşa edilmiş sır Ortam değişkenlerini veya Key Vault kullanma

Sık karşılaşılan hataları giderme

Bu bölüm, istemci gizli verilerini yapılandırırken sık karşılaşabileceğiniz hataları kapsar.

Geçersiz istemci sırrı

Hata:AADSTS7000215: Invalid client secret provided.

Olası nedenler:

  • Gizli değer yanlış kopyalandı. Gizli değerler, kopyalama/yapıştırma işlemleri sırasında kesilebilecek özel karakterler içerebilir.
  • Gizli anahtar, ClientId ayarlanandan farklı bir uygulama kaydı için oluşturulmuştur.
  • Yapılandırma yolu yanlış ve gizli dizi değeri uygulama tarafından okunmuyor.

Çözünürlük:

  1. Azure portalında yeni bir istemci sırrı oluşturun ve tam değerini dikkatle kopyalayın.

  2. Yapılandırmanızdaki ClientId ve TenantId öğelerinin, gizli anahtarın oluşturulduğu uygulama kaydıyla eşleşip eşleşmediğini doğrulayın.

  3. Yapılandırmanın doğru yüklendiğini doğrulamak için bir kesme noktası veya log ifadesi ekleyin.

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

Tarihi geçmiş istemci sırrı

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

Çözünürlük:

  1. Microsoft Entra yönetim merkezi uygulama kaydına gidin.
  2. Sertifikalar ve gizli anahtarlar>İstemci gizli anahtarları altında son kullanma tarihini kontrol edin.
  3. Yeni bir gizli dizi oluşturun ve uygulama yapılandırmanızı güncelleştirin.
  4. Süresi dolan gizli anahtarı portaldan silin.

Yapılandırmada gizli bilgi bulunamadı

Belirti: Uygulama, gizli değeri nedeniyle bir NullReferenceException hata verir veya null yüzünden kimlik doğrulaması başarısız olur.

Olası nedenler:

  • Kullanıcı Sırları proje için başlatılmadı.
  • Ortam değişkeni adı beklenen yapılandırma yoluyla eşleşmiyor.
  • Key Vault yapılandırma kaynağı olarak yapılandırılmamış.
  • Uygulama, Kullanıcı Gizli Dizilerinin yüklenmediği Geliştirme dışı bir ortamda çalışıyor.

Çözünürlük:

  1. Dosyanızda UserSecretsId bir .csproj öğesini denetleyerek Kullanıcı Gizli Dizilerinin başlatıldığını doğrulayın.
  2. dotnet user-secrets list komutunu çalıştırarak gizli anahtarın ayarlandığını doğrulayın.
  3. Yapılandırma yolunun tam olarak eşleştiklerini denetleyin: AzureAd:ClientCredentials:0:ClientSecret.
  4. Geliştirme ortamı dışında çalışıyorsa uygun yapılandırma kaynağının (ortam değişkeni veya Key Vault) kullanılabilir olduğundan emin olun.

İlgili içerik

  • Last updated on