C++ için Azure Identity istemci kitaplığındaki kimlik bilgileri zincirleri

Azure Identity istemci kitaplığı, Azure Core kitaplığının TokenCredential soyut temel sınıfından türetilen genel türler 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, sıradaki ilk kimlik bilgisini kullanarak kimlik doğrulamayı dener. 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 sırasını gösteren

Kimlik bilgileri zincirleri neden kullanılır?

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:

  // Set up credential based on environment (Azure or local development)
  std::shared_ptr<Azure::Core::Credentials::TokenCredential> credential;
  if (std::getenv("WEBSITE_HOSTNAME"))
  {
      credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>();
  }
  else
  {
      credential = std::make_shared<Azure::Identity::AzureCliCredential>();
  }
  

• 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 kimlik bilgisi bir erişim belirteci alamadığında sonraki kimlik bilgisine geçen bir geri dönüş mekanizması içerir.

Zincirlenmiş kimlik bilgisi nasıl seçilir?

C++ ile kimlik bilgisi zincirleme için iki seçenek vardır:

• Önceden yapılandırılmış bir zincirkullanın: DefaultAzureCredential türü tarafından uygulanan önceden yapılandırılmış zinciri kullanın. Bu yaklaşım için DefaultAzureCredential overview bölümüne bakın.
• Özel kimlik bilgileri zinciri oluşturma: Boş bir zincirle başlayın ve yalnızca ihtiyacınız olanları ekleyin. Bu yaklaşım için ChainedTokenCredential genel bakış bölümüne bakın.

DefaultAzureCredential'a genel bakış

DefaultAzureCredential, belirli bir görüşe sahip, önceden yapılandırılmış bir kimlik bilgileri zinciridir. Tasarımı, en yaygın kimlik doğrulama akışları ve geliştirici araçlarının yanı sıra birçok ortamı destekler. Grafik biçiminde, temel zincir şöyle görünür:

Kimlik bilgilerinin DefaultAzureCredential tarafından deneme sırası aşağıdaki gibidir.

Sipariş	Kimlik Belgesi	Açıklama
1	Çevre	Çevre değişkenlerinden oluşan bir koleksiyonu okuyarak, bir uygulama hizmet sorumlusunun (uygulama kullanıcısı) uygulama için yapılandırılıp yapılandırılmadığını belirler. Ö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.
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.
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.
4	Azure CLI	Geliştirici Azure CLI'nın az login komutunu kullanarak Azure'da kimlik doğrulaması yaptıysa, aynı hesabı kullanarak uygulamanın kimliğini Azure'da doğrular.

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

#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

DefaultAzureCredential'ı özelleştirme

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

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:

Bir dev değeri kullanıldığında, zincir yalnızca AzureCliCredential öğesini içerir.

Ortam değişkeninin tanımlandığından ve desteklenen bir dizeye ayarlandığından emin olmak için oluşturucuya true geçinDefaultAzureCredential:

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Önemli

Yukarıda belirtilen oluşturucu aşırı yüklemesi, 1.13.1 ve sonraki paket sürümlerinde desteklenir azure-identity-cpp .

Belirli bir kimlik bilgilerini kullanma

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 AzureCliCredential olarak ayarlayarak AZURE_TOKEN_CREDENTIALS zincirini AzureCliCredential olarak azaltabilirsiniz. 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
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Ortam değişkeninin tanımlandığından ve desteklenen bir dizeye ayarlandığından emin olmak için oluşturucuya true geçinDefaultAzureCredential:

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Önemli

Yukarıda belirtilen oluşturucu aşırı yüklemesi, 1.13.1 ve sonraki paket sürümlerinde desteklenir azure-identity-cpp .

ChainedTokenCredential'a genel bakış

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

#include <azure/identity/azure_cli_credential.hpp>
#include <azure/identity/chained_token_credential.hpp>
#include <azure/identity/managed_identity_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
        Azure::Identity::ChainedTokenCredential::Sources{
            std::make_shared<Azure::Identity::ManagedIdentityCredential>(),
            std::make_shared<Azure::Identity::AzureCliCredential>()});

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

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

Tavsiye

İ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 Identity istemci kitaplığını kullanmaya başlamanın en kolay yoludur, ancak bu kolaylık bazı ödünler ile birlikte gelir. 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.

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 Zincirlenmiş kimlik bilgilerini hata ayıklama bölümüne bakın.
• Performans ek 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 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 uygulamadaki DefaultAzureCredential'in çalışma zamanı davranışını değiştirir.

Zincirli kimlik bilgisi üzerinde hata ayıklama

Beklenmeyen bir sorunu tanılamak veya zincirlenen kimlik bilgilerinin ne yaptığını anlamak için uygulamanızda log kaydını etkinleştirin. Örnek olarak, DefaultAzureCredential'un parametresiz formunun, bir isteği Blob Depolama hesabında kimlik doğrulama amacıyla kullanıldığını varsayalım. Uygulama yerel geliştirme ortamında çalışır ve geliştirici Azure CLI kullanarak Azure'da kimlik doğrulaması yapar. Uygulama çalıştırıldığında, çıkışta aşağıdaki ilgili girdiler görüntülenir:

DEBUG : Identity: Creating DefaultAzureCredential which combines multiple parameterless credentials into a single one.
DefaultAzureCredential is only recommended for the early stages of development, and not for usage in production environment.
Once the developer focuses on the Credentials and Authentication aspects of their application, DefaultAzureCredential needs to be replaced with the credential that is the better fit for the application.
INFO  : Identity: EnvironmentCredential gets created with ClientSecretCredential.
DEBUG : Identity: EnvironmentCredential: 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', and 'AZURE_CLIENT_SECRET' environment variables are set, so ClientSecretCredential with corresponding tenantId, clientId, and clientSecret gets created.
WARN  : Identity: Azure Kubernetes environment is not set up for the WorkloadIdentityCredential credential to work.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2019 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2017 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Cloud Shell source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Azure Arc source.
INFO  : Identity: ManagedIdentityCredential will be created with Azure Instance Metadata Service source.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: AzureCliCredential created.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: DefaultAzureCredential: Created with the following credentials: EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, AzureCliCredential.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from EnvironmentCredential: GetToken(): error response: 400 Bad Request

{"error":"invalid_grant","error_description":"AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance. Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2025-03-07 21:25:44Z","error_codes":[53003],"timestamp":"2025-03-07 21:25:44Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd","error_uri":"https://login.microsoftonline.com/error?code=53003","suberror":"message_only","claims":"{\"access_token\":{\"capolids\":{\"essential\":true,\"values\":[\"cccc2222-dd33-4444-55ee-666666ffffff\"]}}}"}
WARN  : Identity: WorkloadIdentityCredential authentication unavailable. See earlier WorkloadIdentityCredential log messages for details.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from WorkloadIdentityCredential: WorkloadIdentityCredential authentication unavailable. Azure Kubernetes environment is not set up correctly.
INFO  : Identity: DefaultAzureCredential: Successfully got token from ManagedIdentityCredential. This credential will be reused for subsequent calls.
DEBUG : Identity: DefaultAzureCredential: Saved this credential at index 2 for subsequent calls.

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

• EnvironmentCredential, WorkloadIdentityCredentialve ManagedIdentityCredential her bir microsoft Entra erişim belirtecini bu sırayla alamadı.
• ManagedIdentityCredential , "Successfully got token from ManagedIdentityCredential" ile başlayan bir girişle gösterildiği gibi başarılı olur.