Aracılığıyla paylaş

.NET için Azure Kimlik kitaplığındaki kimlik bilgileri zincirleri

Azure Kimlik kitaplığı, Azure Core kitaplığının TokenCredential sınıfından türetilen genel sınıflar olan kimlik bilgilerini sağlar. Kimlik bilgisi, Microsoft Entra Id'den erişim belirteci almak için ayrı bir kimlik doğrulama akışını temsil eder. Bu kimlik bilgileri, denenecek sıralı bir kimlik doğrulama mekanizması dizisi oluşturmak için birbirine zincirlenebilir.

Zincirlenmiş kimlik bilgileri nasıl çalışır?

Çalışma zamanında, kimlik bilgisi zinciri dizinin ilk kimlik bilgilerini kullanarak kimlik doğrulaması yapmaya çalışır. Bu kimlik bilgisi bir erişim belirteci alamazsa, bir erişim belirteci başarıyla alınana kadar dizideki bir sonraki kimlik bilgisi denenir ve bu şekilde devam edilir. Aşağıdaki sıralı diyagramda bu davranış gösterilmektedir:

Kimlik bilgisi zinciri dizisi diyagramı

Kimlik bilgisi zincirlerini neden kullanmalısınız?

Zincirlenmiş kimlik bilgileri aşağıdaki avantajları sunabilir:

  • Ortam tanıma: Uygulamanın çalıştığı ortama göre en uygun kimlik bilgilerini otomatik olarak seçer. Bu olmadan, aşağıdaki gibi bir kod yazmanız gerekir:

    TokenCredential credential;

if (app.Environment.IsProduction() || app.Environment.IsStaging())
{
    credential = new ManagedIdentityCredential(
        ManagedIdentityId.FromUserAssignedClientId(userAssignedClientId));
}
else
{
    // local development environment
    credential = new VisualStudioCredential();
}

  • Sorunsuz geçişler: Uygulamanız, kimlik doğrulama kodunu değiştirmeden yerel geliştirmeden hazırlama veya üretim ortamınıza geçebilir.

  • Geliştirilmiş dayanıklılık: Önceki bir erişim belirtecini alamayınca sonraki kimlik bilgilerine taşınan bir geri dönüş mekanizması içerir.

Zincirlenmiş kimlik bilgisi seçme

Kimlik bilgisi zincirlemenin iki farklı felsefesi vardır:

  • Bir zinciri "yok etme": Önceden yapılandırılmış bir zincirle başlayın ve ihtiyacınız olmayanları hariç tutun. Bu yaklaşım için DefaultAzureCredential genel bakış bölümüne bakın.
  • Bir zinciri "derleyin": Boş bir zincirle başlayın ve yalnızca ihtiyacınız olanı ekleyin. Bu yaklaşım için ChainedTokenCredential genel bakış bölümüne bakın.

DefaultAzureCredential'a genel bakış

DefaultAzureCredential , önceden yapılandırılmış, önceden yapılandırılmış bir kimlik bilgileri zinciridir. En yaygın kimlik doğrulama akışları ve geliştirici araçlarının yanı sıra birçok ortamı destekleyecek şekilde tasarlanmıştır. Grafik biçiminde, temel zincir şöyle görünür:

DefaultAzureCredential kimlik doğrulama akışını gösteren diyagram.

Kimlik bilgilerinin hangi sırayla denendiği DefaultAzureCredential aşağıda belirtilmiştir.

Sipariş Referans Açıklama Varsayılan olarak etkinleştirilsin mi?
1 Ortam Uygulama hizmet sorumlusunun (uygulama kullanıcısı) uygulama için yapılandırılıp yapılandırılmadığını belirlemek için ortam değişkenlerinden oluşan bir koleksiyonu okur. Öyleyse, DefaultAzureCredential uygulamanın kimliğini Azure'da doğrulamak için bu değerleri kullanır. Bu yöntem genellikle sunucu ortamlarında kullanılır, ancak yerel olarak geliştirirken de kullanılabilir. Evet
2 İş Yükü Kimliği Uygulama İş Yükü Kimliği etkinleştirilmiş bir Azure konağına dağıtıldıysa bu hesabın kimliğini doğrula. Evet
3 Yönetilen Kimlik Uygulama Yönetilen Kimlik etkinleştirilmiş bir Azure konağına dağıtılırsa, bu Yönetilen Kimliği kullanarak uygulamanın kimliğini Azure'da doğrularsınız. Evet
4 Visual Studio Geliştirici, Visual Studio'da oturum açarak Azure'da kimlik doğrulaması yaptıysa, aynı hesabı kullanarak uygulamanın kimliğini Azure'da doğrulayın. Evet
5 Visual Studio Code Geliştiricinin kimliği Visual Studio Code'un Azure Kaynakları uzantısıyla doğrulandıysa ve Azure.Identity.Broker paketi yüklüyse bu hesabın kimliğini doğrulayın. Evet
6 Azure CLI Geliştirici Azure CLI'nın komutunu kullanarak Azure'da az login kimlik doğrulaması yaptıysa, aynı hesabı kullanarak uygulamanın kimliğini Azure'da doğrular. Evet
7 Azure PowerShell Geliştirici Azure PowerShell'in cmdlet'ini kullanarak Azure'da Connect-AzAccount kimlik doğrulaması yaptıysa, aynı hesabı kullanarak uygulamanın kimliğini Azure'da doğrulayın. Evet
8 Azure Geliştirici CLI'sı Geliştirici, Azure Geliştirici CLI'sinin komutunu kullanarak Azure'da azd auth login kimlik doğrulaması yaptıysa, bu hesapla kimlik doğrulamasından geçin. Evet
9 Etkileşimli tarayıcı Etkinleştirilirse, geçerli sistemin varsayılan tarayıcısı aracılığıyla geliştiricinin kimliğini etkileşimli olarak doğrular. Hayır
10 Aracı Bir aracı aracılığıyla işletim sisteminde oturum açan varsayılan hesabı kullanarak kimlik doğrulaması yapar. Azure.Identity.Broker paketinin yüklü olmasını gerektirir. Evet

En basit haliyle parametresiz sürümünü DefaultAzureCredential aşağıdaki gibi kullanabilirsiniz:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));
});

İpucu

UseCredential Önceki kod parçacığındaki yöntemin ASP.NET Core uygulamalarında kullanılması önerilir. Daha fazla bilgi için bkz . ASP.NET Core uygulamalarında .NET için Azure SDK'yı kullanma.

DefaultAzureCredential'ı özelleştirme

Aşağıdaki bölümlerde, zincire hangi kimlik bilgilerinin dahil olduğunu denetlemeye yönelik stratejiler açıklanmaktadır.

Tek bir kimlik bilgisini dışlama

Tek bir kimlik bilgisini DefaultAzureCredential hariç tutmak için Exclude içinde ilgili -önekli özelliği kullanın. Örneğin:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new DefaultAzureCredential(
        new DefaultAzureCredentialOptions
        {
            ExcludeEnvironmentCredential = true,
            ExcludeManagedIdentityCredential = true,
            ExcludeWorkloadIdentityCredential = true,
        }));
});

Yukarıdaki kod örneğinde, EnvironmentCredential, ManagedIdentityCredentialve WorkloadIdentityCredential kimlik bilgisi zincirinden kaldırılır. Sonuç olarak, denenecek ilk kimlik bilgisi olur VisualStudioCredential. Değiştirilen zincir yalnızca geliştirme zamanı kimlik bilgilerini içerir ve şöyle görünür:

Dışlama özelliklerini kullanan DefaultAzureCredential

Not

InteractiveBrowserCredential varsayılan olarak dışlanır ve bu nedenle önceki diyagramda gösterilmez. eklemek InteractiveBrowserCredentialiçin oluşturucuya true geçirin DefaultAzureCredential(Boolean) veya özelliğini DefaultAzureCredentialOptions.ExcludeInteractiveBrowserCredential olarak falseayarlayın.

Daha fazla Excludeön ekli özellik olarak ayarlandığında true (kimlik bilgisi dışlamaları yapılandırılır), kullanmanın DefaultAzureCredential avantajları azalır. Böyle durumlarda, ChainedTokenCredential daha iyi bir seçimdir ve daha az kod gerektirir. Göstermek için, bu iki kod örneği aynı şekilde davranır:

credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeManagedIdentityCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
        ExcludeBrokerCredential = true,
    });

Kimlik bilgisi türü kategorisini dışlama

Tüm Developer tool veya Deployed service kimlik bilgilerini dışlamak için ortam değişkenini AZURE_TOKEN_CREDENTIALSprod sırasıyla veya devolarak ayarlayın. değeri prod kullanıldığında, temel alınan kimlik bilgisi zinciri aşağıdaki gibi görünür:

DefaultAzureCredential, AZURE_TOKEN_CREDENTIALS 'prod' olarak ayarlandığında

değeri dev kullanıldığında, zincir aşağıdaki gibi görünür:

AZURE_TOKEN_CREDENTIALS 'dev' olarak ayarlanmış DefaultAzureCredential

Ortam değişkeninin tanımlandığından ve desteklenen bir dizeye ayarlandığından emin olmak için oluşturucu aşırı yüklemesini DefaultAzureCredential(String, DefaultAzureCredentialOptions)kullanın.

Belirli bir kimlik bilgisini kullan

Biri dışındaki tüm kimlik bilgilerini dışlamak için ortam değişkenini AZURE_TOKEN_CREDENTIALS kimlik bilgisi adına ayarlayın. Örneğin, DefaultAzureCredential'yi VisualStudioCredential olarak ayarlayarak AZURE_TOKEN_CREDENTIALS zincirini VisualStudioCredential olarak küçültebilirsiniz. Dize karşılaştırması büyük/küçük harfe duyarsız bir şekilde gerçekleştirilir. Ortam değişkeni için geçerli dize değerleri şunlardır:

  • AzureCliCredential
  • AzureDeveloperCliCredential
  • AzurePowerShellCredential
  • BrokerCredential
  • EnvironmentCredential
  • InteractiveBrowserCredential
  • ManagedIdentityCredential
  • VisualStudioCredential
  • VisualStudioCodeCredential
  • WorkloadIdentityCredential

Önemli

Ortam değişkeni, AZURE_TOKEN_CREDENTIALS paket sürümlerinden 1.15.0 ve sonrasında tek tek kimlik bilgisi adlarını destekler.

Ortam değişkeninin tanımlandığından ve desteklenen bir dizeye ayarlandığından emin olmak için oluşturucu aşırı yüklemesini DefaultAzureCredential(String, DefaultAzureCredentialOptions)kullanın.

ChainedTokenCredential'a genel bakış

ChainedTokenCredential , uygulamanızın gereksinimlerine uygun kimlik bilgileri eklediğiniz boş bir zincirdir. Örneğin:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new AzurePowerShellCredential(),
        new VisualStudioCredential()));
});

Yukarıdaki kod örneği, iki geliştirme zamanı kimlik bilgisi içeren uyarlanmış bir kimlik bilgisi zinciri oluşturur. AzurePowerShellCredential önce denendi, ardından gerekirse VisualStudioCredential. Grafik biçiminde zincir şöyle görünür:

ChainedTokenCredential

İpucu

İyileştirilmiş performans için ChainedTokenCredential kimlik bilgisi sıralamasını en az kullanılan kimlik bilgilerine kadar iyileştirin.

DefaultAzureCredential için kullanım kılavuzu

DefaultAzureCredential Şüphesiz Azure Kimlik kitaplığını kullanmaya başlamanın en kolay yoludur, ancak bu kolaylıktan ödünler alınıyor. Uygulamanızı Azure'a dağıttığınızda uygulamanın kimlik doğrulama gereksinimlerini anlamanız gerekir. Bu nedenle, DefaultAzureCredentialTokenCredentialgibi belirli bir ManagedIdentityCredential uygulamasıyla değiştirin. Seçenekler için Türetilmiş listesine bakın.

Bunun nedeni şu şekildedir:

  • Hata ayıklama zorlukları: Kimlik doğrulaması başarısız olduğunda, hata ayıklamak ve sorunlu kimlik bilgilerini belirlemek zor olabilir. Bir kimlik bilgisinden diğerine ilerleme durumunu ve her birinin başarı/başarısızlık durumunu görmek için günlüğe kaydetmeyi etkinleştirmeniz gerekir. Daha fazla bilgi için bkz . Zincirlenmiş kimlik bilgilerinin hatalarını ayıklama.
  • Performans yükü: Birden çok kimlik bilgilerini sıralı olarak deneme işlemi performans ek yüküne neden olabilir. Örneğin, yerel bir geliştirme makinesinde çalışırken yönetilen kimlik kullanılamaz. Sonuç olarak, ManagedIdentityCredential ilgili Excludeön ekli özelliği aracılığıyla açıkça devre dışı bırakılmadığı sürece yerel geliştirme ortamında her zaman başarısız olur.
  • Öngörülemeyen davranış: DefaultAzureCredential Belirli ortam değişkenlerinin varlığını denetler. Birinin konak makinede sistem düzeyinde bu ortam değişkenlerini eklemesi veya değiştirmesi mümkündür. Bu değişiklikler genel olarak uygulanır ve bu nedenle bu makinede çalışan herhangi bir uygulamada çalışma zamanında davranışını DefaultAzureCredential değiştirir. Öngörülemezlik hakkında daha fazla bilgi için bkz. Üretim ortamlarında belirleyici kimlik bilgilerini kullanma.

Zincirlenmiş kimlik bilgisinde hata ayıklama

Beklenmeyen bir sorunu tanılamak veya zincirlenmiş kimlik bilgilerinin ne yaptığını anlamak için uygulamanızda günlüğe kaydetmeyi etkinleştirin. İsteğe bağlı olarak günlükleri yalnızca Azure Kimlik kitaplığından yayılan olaylara göre filtreleyin. Örneğin:

using AzureEventSourceListener listener = new((args, message) =>
{
    if (args is { EventSource.Name: "Azure-Identity" })
    {
        Console.WriteLine(message);
    }
}, EventLevel.LogAlways);

Çizim amacıyla, parametresiz biçiminin DefaultAzureCredential Log Analytics çalışma alanına yönelik bir isteğin kimliğini doğrulamak için kullanıldığını varsayalım. Uygulama yerel geliştirme ortamında çalıştırıldı ve Visual Studio'nun kimliği bir Azure hesabında doğrulandı. Uygulama bir sonraki çalıştırışında, çıkışta aşağıdaki ilgili girdiler görüntülenir:

DefaultAzureCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot
WorkloadIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
WorkloadIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/workloadidentitycredential/troubleshoot
ManagedIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
ManagedIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): ManagedIdentityCredential authentication unavailable. No response received from the managed identity endpoint.
VisualStudioCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
VisualStudioCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00
DefaultAzureCredential credential selected: Azure.Identity.VisualStudioCredential
DefaultAzureCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00

Yukarıdaki çıkışta şunların olduğuna dikkat edin:

  • EnvironmentCredential, WorkloadIdentityCredentialve ManagedIdentityCredential her bir microsoft Entra erişim belirtecini bu sırayla alamadı.
  • DefaultAzureCredential credential selected:-prefixed girdisi seçilen kimlik bilgilerini gösterir;VisualStudioCredential bu durumda. Başarılı olduğundan VisualStudioCredential , bunun ötesinde hiçbir kimlik bilgisi kullanılmadı.
  • Last updated on