Cadeias de credenciais na biblioteca de Identidade do Azure para JavaScript

A biblioteca de identidade do Azure fornece credenciais—classes públicas que implementam a interface TokenCredential da biblioteca do Azure Core. Uma credencial representa um fluxo de autenticação distinto para obter um token de acesso do Microsoft Entra ID. Essas credenciais podem ser encadeadas para formar uma sequência ordenada de mecanismos de autenticação a serem tentados.

Como funciona uma credencial encadeada

Em tempo de execução, uma cadeia de credenciais tenta realizar a autenticação usando a primeira credencial da sequência. Se essa credencial não conseguir adquirir um token de acesso, a próxima credencial na sequência será tentada e assim por diante, até que um token de acesso seja obtido com êxito. O diagrama de sequência a seguir ilustra esse comportamento:

Por que usar cadeias de credenciais

Uma credencial encadeada pode oferecer os seguintes benefícios:

• Reconhecimento de ambiente: seleciona automaticamente a credencial mais apropriada com base no ambiente em que o aplicativo está sendo executado. Sem ele, você teria que escrever um código como este:

  import { 
      ManagedIdentityCredential, 
      AzureCliCredential 
  } from "@azure/identity";
  
  let credential;
  if (process.env.NODE_ENV === "production") {
      credential = new ManagedIdentityCredential();
  } else {
      credential = new AzureCliCredential();
  }
  

• Transições perfeitas: seu aplicativo pode passar do desenvolvimento local para o ambiente de preparo ou produção sem alterar o código de autenticação.

• Resiliência aprimorada: inclui um mecanismo de fallback que se move para a próxima credencial quando a anterior não consegue adquirir um token de acesso.

Como escolher uma credencial encadeada

Há duas abordagens diferentes para encadeamento de credenciais:

• "Destruir" uma cadeia: comece com uma cadeia pré-configurada e exclua o que você não precisa. Para essa abordagem, consulte a seção Visão geral do DefaultAzureCredential.
• "Monte" uma cadeia: comece com uma cadeia vazia e inclua apenas o que você precisa. Para essa abordagem, consulte a seção Visão geral do ChainedTokenCredential.

Visão geral de DefaultAzureCredential

DefaultAzureCredential é uma cadeia de credenciais opinativa e pré-configurada. Ele foi projetado para dar suporte a muitos ambientes, juntamente com os fluxos de autenticação mais comuns e as ferramentas de desenvolvedor. Na forma gráfica, a cadeia subjacente tem esta aparência:

A ordem na qual as credenciais de tentativas DefaultAzureCredential seguem.

Em sua forma mais simples, você pode usar a versão sem parâmetros de DefaultAzureCredential da seguinte maneira:

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
);

Como personalizar DefaultAzureCredential

As seções a seguir descrevem estratégias para controlar quais credenciais estão incluídas na cadeia.

Excluir uma categoria de tipo de credencial

Para excluir todas Developer tool ou Deployed service credenciais, defina a variável AZURE_TOKEN_CREDENTIALS de ambiente como prod ou dev, respectivamente. Quando um valor é prod usado, a cadeia de credenciais subjacentes tem a seguinte aparência:

Quando um valor é dev usado, a cadeia tem a seguinte aparência:

Para garantir que a variável de ambiente seja definida e definida como uma cadeia de caracteres com suporte, defina a propriedade RequiredEnvVars como AZURE_TOKEN_CREDENTIALS:

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

Usar uma credencial específica

Para excluir todas as credenciais, exceto uma, defina a variável AZURE_TOKEN_CREDENTIALS de ambiente como o nome da credencial. Por exemplo, você pode reduzir a DefaultAzureCredential cadeia definindo AzureCliCredentialAZURE_TOKEN_CREDENTIALS como AzureCliCredential. A comparação de cadeia de caracteres é executada de maneira que não diferencia maiúsculas de minúsculas. Os valores de cadeia de caracteres válidos para a variável de ambiente incluem:

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Para garantir que a variável de ambiente seja definida e definida como uma cadeia de caracteres com suporte, defina a propriedade requiredEnvVars como AZURE_TOKEN_CREDENTIALS:

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

Visão geral de ChainedTokenCredential

ChainedTokenCredential é uma cadeia vazia à qual você pode adicionar credenciais para atender às necessidades do seu aplicativo. Por exemplo:

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
);

O exemplo de código anterior cria uma cadeia de credenciais personalizada composta de duas credenciais de tempo de desenvolvimento. AzureCliCredential é tentado primeiro, seguido por VisualStudioCodeCredential, se necessário. Na forma gráfica, a cadeia tem esta aparência:

Diretrizes de uso para DefaultAzureCredential

DefaultAzureCredential é, sem dúvida, a maneira mais fácil de começar a usar a biblioteca de Identidades do Azure, mas com essa conveniência vêm desvantagens. Depois de implantar seu aplicativo no Azure, você deverá entender os requisitos de autenticação do aplicativo. Por esse motivo, substitua DefaultAzureCredential por uma implementação TokenCredential específica, como ManagedIdentityCredential.

Veja o motivo:

• Desafios de Depuração: No caso de falha na autenticação, pode ser desafiador depurar e identificar a credencial problemática. Você precisa habilitar o log para ver a progressão de uma credencial para a próxima e o status de sucesso/falha de cada uma. Para obter mais informações, consulte Depurar uma credencial.
• Sobrecarga de desempenho: o processo de tentar sequencialmente várias credenciais pode introduzir sobrecarga de desempenho. Por exemplo, ao executar em um computador de desenvolvimento local, a identidade gerenciada não está disponível. Consequentemente, ManagedIdentityCredential sempre falha no ambiente de desenvolvimento local.
• Comportamento imprevisível: DefaultAzureCredential verifica a presença de determinadas variáveis de ambiente. É possível que alguém possa adicionar ou modificar essas variáveis de ambiente no nível do sistema no computador host. Essas alterações se aplicam globalmente e, portanto, alteram o comportamento de DefaultAzureCredential em runtime em qualquer aplicativo em execução nesse computador.

Depurar uma credencial

Para diagnosticar um problema inesperado ou entender o que uma credencial está fazendo, ative o log em seu aplicativo. Por exemplo:

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.

Na saída anterior, observe que DefaultAzureCredential adquiriu com êxito um token usando AzureCliCredential.