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

Azure Kimlik kitaplığı, Azure Core kitaplığının TokenCredential arabirimini uygulayan credentials olarak bilinen ortak sınıflar sağlar. Kimlik bilgisi, Microsoft Entra ID 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 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:

  import com.azure.core.credential.TokenCredential;
  import com.azure.identity.AzureCliCredentialBuilder;
  import com.azure.identity.ManagedIdentityCredentialBuilder;
  
  // Code omitted for brevity
  
  TokenCredential credential = null;
  
  // Set up credential based on environment (Azure or local development)
  String environment = System.getenv("ENV");
  
  if (environment != null && environment.equals("production")) {
      credential = new ManagedIdentityCredentialBuilder()
          .clientId(userAssignedClientId)
          .build();
  } else {
      credential = new AzureCliCredentialBuilder()
          .build();
  }
  

• 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

Kimlik bilgisi zincirleme için iki farklı yaklaşım vardır:

• Önceden yapılandırılmış bir zincir kullanma: En yaygın kimlik doğrulama senaryolarını kapsayan, belirli tercihler barındıran ve önceden oluşturulmuş bir zincirle başlayın. 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, belirli bir yaklaşımı benimsemiş, ö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:

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

Sipariş	Kimlik Belgesi	Açıklama
1	Çevre	Bir uygulama hizmet sorumlusunun (uygulama kullanıcısı) uygulama için yapılandırılıp yapılandırılmadığını belirlemek amacıyla çevre değişkenleri koleksiyonu okunur. Öyleyse, uygulamanın kimliğini doğrulamak için bu değerleri kullanarak DefaultAzureCredential Azure ile iletişime geçer. Bu yöntem yerel olarak geliştirirken kullanılabilir, ancak çoğunlukla sunucu ortamlarında kullanılır.
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 etkin bir Azure konağına dağıtılırsa, bu Yönetilen Kimliği kullanarak Azure için uygulamanın kimliğini doğrula.
4	IntelliJ	Geliştirici intelliJ için Azure Toolkit aracılığıyla kimlik doğrulaması yaptıysa bu hesabın kimliğini doğrula.
5	Visual Studio Code	Visual Studio Code'un Azure Resources uzantısı üzerinden kimlik doğrulaması yapılmışsa ve azure-identity-broker paketi yüklüyse, o hesabın kimliğini doğrulayın.
6	Azure CLI	Geliştirici Azure CLI az login komutunu kullanarak Azure kimliğini doğruladıysa, aynı hesabı kullanarak Azure için uygulamanın kimliğini doğrulayın.
7	Azure PowerShell	Geliştirici Azure PowerShell Connect-AzAccount cmdlet'ini kullanarak Azure kimliğini doğruladıysa, aynı hesabı kullanarak Azure için uygulamanın kimliğini doğrulayın.
8	Azure Geliştirici CLI	Geliştirici, Azure Developer CLI'nin azd auth login komutunu kullanarak Azure'da kimlik doğrulaması yaptıysa, bu hesapla kimlik doğrulamasını gerçekleştirin.
9	Aracısı	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ı gereklidir, çünkü InteractiveBrowserCredential aracı özellikli bir örneği olarak kullanıldığından.

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

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Code omitted for brevity

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .build();

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:

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

Önemli

Ortam AZURE_TOKEN_CREDENTIALS değişkeni 1.16.1 ve sonraki paket sürümlerinde desteklenir azure-identity .

Ortam değişkeninin tanımlandığından ve desteklenen bir dizeye ayarlandığından emin olmak için yöntemini requireEnvVars aşağıdaki gibi çağırın:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

Önemli

requireEnvVars yöntemi, 1.18.0 ve sonraki paket sürümlerinde kullanılabilirazure-identity.

Varsayılan AZURE_TOKEN_CREDENTIALSyerine özel bir ortam değişkeni adı kullanmak için özel değişkeninize bir başvuru oluşturmak için kullanın AzureIdentityEnvVars.fromString() :

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.fromString("MY_CUSTOM_TOKEN_CREDENTIALS"))
    .build();

Uyarı

yöntemi, requireEnvVars belirtilen ortam değişkenleri ayarlanmamışsa veya boşsa bir IllegalStateException oluşturur.

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
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• IntelliJCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Önemli

AZURE_TOKEN_CREDENTIALS ortam değişkeni, 1.17.0 ve sonraki sürümlerdeki paketlerde tek tek kimlik bilgisi adlarını azure-identity destekler.

Ortam değişkeninin tanımlandığından ve desteklenen bir dizeye ayarlandığından emin olmak için requireEnvVars yöntemini aşağıdaki gibi çağırın:

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS)
    .build();

ChainedTokenCredential'a genel bakış

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

import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;
import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;
import com.azure.identity.IntelliJCredential;
import com.azure.identity.IntelliJCredentialBuilder;

// Code omitted for brevity

AzureCliCredential cliCredential = new AzureCliCredentialBuilder()
    .build();
IntelliJCredential ijCredential = new IntelliJCredentialBuilder()
    .build();

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addLast(cliCredential)
    .addLast(ijCredential)
    .build();

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

İ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 dağıttığınızda, uygulamanın kimlik doğrulama gereksinimlerini anlamanız ve DefaultAzureCredential senaryonuz için uygun olup olmadığını düşünmeniz gerekir.

DefaultAzureCredential önemli bir avantaj sunar: Uygulama kodunuzu belirli kimlik doğrulama mekanizmalarından ayrıştırarak kodu değiştirmeden kimlik doğrulama yapılandırmanızı değiştirmenize olanak tanır. Üretim kimlik doğrulamasını bilinçli olarak yapılandıran deneyimli geliştiriciler için bu esneklik değerli olabilir. Ancak bu esneklik olası dezavantajlarla birlikte gelir:

• 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 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 çevre 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ı sırasında DefaultAzureCredential'in davranışını değiştirir.
• İzin uyuşmazlıkları: DefaultAzureCredential Bu kimlik bilgilerinin doğru izinlere sahip olup olmadığına bakılmaksızın, bir belirteci başarıyla alan ilk kimlik bilgisinde durur. Örneğin, yerel geliştirme kimlik bilgileri üretim tarafından yönetilen kimlikten daha geniş izinlere sahip olabilir ve uygulamanın yerel olarak çalışmasına, ancak dağıtımdan sonra yetkilendirme denetimlerinin başarısız olmasına neden olabilir.

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.

Çizim amacıyla, DefaultAzureCredential parametresiz biçiminin bir Blob Storage hesabına yönelik isteğin kimliğini doğrulamak için kullanıldığını varsayalım. Uygulama yerel geliştirme ortamında çalışır ve geliştirici Azure CLI kullanarak Azure kimliğini doğrular. Uygulama çalıştırıldığında, çıkışta aşağıdaki ilgili girdiler görüntülenir:

[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential EnvironmentCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential WorkloadIdentityCredential is unavailable.
[ForkJoinPool.commonPool-worker-1] WARN com.microsoft.aad.msal4j.ConfidentialClientApplication - [Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd] Execution of class com.microsoft.aad.msal4j.AcquireTokenByClientCredentialSupplier failed: java.util.concurrent.ExecutionException: com.azure.identity.CredentialUnavailableException: ManagedIdentityCredential authentication unavailable. Connection to IMDS endpoint cannot be established.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential ManagedIdentityCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential IntelliJCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential VisualStudioCodeCredential is unavailable.
[main] INFO com.azure.identity.ChainedTokenCredential - Azure Identity => Attempted credential AzureCliCredential returns a token

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

• EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, IntelliJCredential ve VisualStudioCodeCredential bu sırayla bir Microsoft Entra erişim belirteci alamadı.
• Çağrı, AzureCliCredential.getToken ile biten girdide gösterildiği gibi başarıyla gerçekleşir. AzureCliCredential başarılı olduğundan dolayı, bunun ötesinde hiçbir kimlik bilgisi denenmedi.