Aracılığıyla paylaş

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

Azure Kimlik kitaplığı, Azure Core kitaplığının TokenCredential arabirimini uygulayan genel sınıflar kimlik bilgilerisağ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:

Başarılı belirteç alımına kadar birden çok kimlik bilgisi arasında sıralı denemelerle kimlik bilgisi zinciri kimlik doğrulama akışını gösteren 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:

    import { 
    ManagedIdentityCredential, 
    AzureCliCredential 
} from "@azure/identity";

let credential;
if (process.env.NODE_ENV === "production") {
    credential = new ManagedIdentityCredential();
} else {
    credential = new 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?

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

  • Bir zinciri "daha basit hale getirme": Önceden yapılandırılmış bir zincirle başlayın ve ihtiyacınız olmayanları hariç tutun. Bu yaklaşım için DefaultAzureCredential overview 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, varsayılan olarak yapılandırılmış ve belirli bir düzeni izleyen 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:

EnvironmentCredential ile BrokerCredential arasında tam sırayı gösteren DefaultAzureCredential kimlik doğrulama akışının diyagramı.

DefaultAzureCredential kimlik bilgilerini deneme sırası aşağıdadır.

Sipariş Kimlik 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. Bu durumda, 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. Yes
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. Yes
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. Yes
4 Visual Studio Code Geliştiricinin kimliği Visual Studio Code'un Azure Kaynakları uzantısıyla doğrulandıysa ve @azure/identity-vscode paketi yüklüyse bu hesabın kimliğini doğrulayın. Yes
5 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. Yes
6 Azure PowerShell Geliştirici Azure PowerShell'in Connect-AzAccount cmdlet'ini kullanarak Azure'da kimlik doğrulaması yaptıysa, aynı hesabı kullanarak uygulamanın kimliğini Azure'da doğrulayın. Yes
7 Azure Geliştirici CLI Geliştirici, Azure Geliştirici CLI'sının azd auth login komutunu kullanarak Azure'da kimlik doğrulaması yaptıysa, bu hesapla kimlik doğrulamasından geçin. Yes
8 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ını gerektirir. Yes

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

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    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:

Yalnızca Ortam, İş Yükü Kimliği ve Yönetilen Kimlik gibi dağıtılmış hizmet kimlik bilgilerini gösteren ve AZURE_TOKEN_CREDENTIALS 'prod' olarak ayarlanmış DefaultAzureCredential zincirinin diyagramı.

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

Visual Studio Code, Azure CLI, Azure PowerShell, Azure Geliştirici CLI ve Aracı gibi yalnızca geliştirici aracı kimlik bilgilerini gösteren ve AZURE_TOKEN_CREDENTIALS 'dev' olarak ayarlanmış DefaultAzureCredential zincirinin diyagramı.

Ortam değişkeninin tanımlandığından ve desteklenen bir dizeye ayarlandığından emin olmak için requiredEnvVars özelliğini olarak AZURE_TOKEN_CREDENTIALSayarlayın:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

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
  • ManagedIdentityCredential
  • VisualStudioCodeCredential
  • WorkloadIdentityCredential

Önemli

Ortam değişkeni, AZURE_TOKEN_CREDENTIALS 4.11.0 ve sonraki paket sürümlerinde 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 requiredEnvVars özelliğini olarak AZURE_TOKEN_CREDENTIALSayarlayın:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

ChainedTokenCredential'a genel bakış

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

import { 
    ChainedTokenCredential, 
    AzureCliCredential, 
    VisualStudioCodeCredential 
} from "@azure/identity";

const credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new VisualStudioCodeCredential()
);

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

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

İkincil geri dönüş seçeneği olarak VisualStudioCodeCredential ile birincil kimlik doğrulama yöntemi olarak AzureCliCredential'i gösteren ChainedTokenCredential yapılandırması diyagramı.

Bahşiş

İ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.

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. Kimlik bilgisinde hata ayıklama.
  • 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 uygulamada çalışma zamanında DefaultAzureCredential davranışını değiştirir.

Kimlik bilgisinde hata ayıklama

Beklenmedik bir sorunu tanılamak veya kimlik bilgilerinin işlevini anlamak için uygulamanızda günlüğe kaydetmeyi etkinleştirin. Örneğin:

import { setLogLevel, AzureLogger } from "@azure/logger";
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

// Constant for the Azure Identity log prefix
const AZURE_IDENTITY_LOG_PREFIX = "azure:identity";

// override logging to output to console.log (default location is stderr)
// only log messages that start with the Azure Identity log prefix
setLogLevel("verbose");
AzureLogger.log = (...args) => {
  const message = args[0];
  if (typeof message === 'string' && message.startsWith(AZURE_IDENTITY_LOG_PREFIX)) {
    console.log(...args);
  }
};

// Get storage account name from environment variable
const storageAccountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!storageAccountName) {
    throw new Error("AZURE_STORAGE_ACCOUNT_NAME environment variable is required");
}

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});


const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

azure:identity:info EnvironmentCredential => Found the following environment variables: 
azure:identity:verbose EnvironmentCredential => AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: undefined; sendCertificateChain: false
azure:identity:info WorkloadIdentityCredential => Found the following environment variables:
azure:identity:warning DefaultAzureCredential => Skipped createDefaultWorkloadIdentityCredential because of an error creating the credential: CredentialUnavailableError: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => Using DefaultToImds managed identity.
azure:identity:warning DefaultAzureCredential => Skipped createDefaultBrokerCredential because of an error creating the credential: Error: Broker for WAM was requested, but no plugin was configured or no authentication record was found. You must install the @azure/identity-broker plugin package (npm install --save @azure/identity-broker) and enable it by importing `useIdentityPlugin` from `@azure/identity` and calling useIdentityPlugin(nativeBrokerPlugin) before using enableBroker.
azure:identity:info DefaultAzureCredential => getToken() => Skipping createDefaultWorkloadIdentityCredential, reason: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => getToken() => Using the MSAL provider for Managed Identity.
azure:identity:info ManagedIdentityCredential - Token Exchange => ManagedIdentityCredential - Token Exchange: Unavailable. The environment variables needed are: AZURE_CLIENT_ID (or the client ID sent through the parameters), AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE
azure:identity:info ManagedIdentityCredential => getToken() => MSAL Identity source: DefaultToImds
azure:identity:info ManagedIdentityCredential => getToken() => Using the IMDS endpoint to probe for availability.
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Pinging the Azure IMDS endpoint
azure:identity:verbose ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Caught error RestError: connect ENETUNREACH 169.254.169.254:80
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: The Azure IMDS endpoint is unavailable
azure:identity:error ManagedIdentityCredential => getToken() => ERROR. Scopes: https://storage.azure.com/.default. Error message: Attempted to use the IMDS endpoint, but it is not available..
azure:identity:info AzureCliCredential => getToken() => Using the scope https://storage.azure.com/.default
azure:identity:info AzureCliCredential => getToken() => expires_on is available and is valid, using it
azure:identity:info AzureCliCredential => getToken() => SUCCESS. Scopes: https://storage.azure.com/.default.

Önceki çıktıda DefaultAzureCredential kullanılarak AzureCliCredential ile başarıyla bir belirteç alındığına dikkat edin.

  • Last updated on