Cadeias de credenciais na biblioteca de Identidades 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 adquirir 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

Durante o tempo de execução, uma cadeia de credenciais tenta autenticar utilizando 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:

Diagrama de uma sequência de cadeia de credenciais mostrando tentativas de autenticação progredindo através de várias credenciais até que um token de acesso seja obtido.

Por que usar cadeias de credenciais

Uma credencial encadeada pode oferecer os seguintes benefícios:

Perceção do ambiente: seleciona automaticamente a credencial mais apropriada com base no ambiente em que a aplicação está a ser executada. 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 preparação 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 o anterior não consegue adquirir um token de acesso.

Como escolher uma credencial encadeada

Há duas abordagens diferentes para o encadeamento de credenciais:

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

Visão geral de DefaultAzureCredential

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

A ordem pela qual DefaultAzureCredential tenta as credenciais é a seguinte.

Encomenda	Credencial	Descrição	Ativado por predefinição?
1	Ambiente	Lê uma coleção de variáveis de ambiente para determinar se um principal de serviço da aplicação (usuário da aplicação) está configurado para a aplicação. Em caso afirmativo, `DefaultAzureCredential` usa esses valores para autenticar o aplicativo no Azure. Este método é mais frequentemente usado em ambientes de servidor, mas também pode ser usado ao desenvolver localmente.	Yes
2	Identidade da carga de trabalho	Se o aplicativo for implantado em um host do Azure com a Identidade da Carga de Trabalho habilitada, autentique essa conta.	Yes
3	Identidade Gerenciada	Se o aplicativo for implantado em um host do Azure com a Identidade Gerenciada habilitada, autentique o aplicativo no Azure usando essa Identidade Gerenciada.	Yes
4	Código do Visual Studio	Se o desenvolvedor autenticado por meio da extensão Recursos do Azure do Visual Studio Code e o pacote @azure/identity-vscode estiver instalado, autentique essa conta.	Yes
5	CLI do Azure	Se o desenvolvedor se autenticou no Azure usando o comando `az login` da CLI do Azure, autentique o aplicativo no Azure usando essa mesma conta.	Yes
6	Azure PowerShell	Se o desenvolvedor se autenticou no Azure usando o cmdlet do `Connect-AzAccount` Azure PowerShell, autentique o aplicativo no Azure usando essa mesma conta.	Yes
7	CLI do Azure para Desenvolvedores	Se o desenvolvedor se autenticou no Azure usando o comando `azd auth login` da CLI do Azure Developer, autentique-se com essa conta.	Yes
8	Broker	Autentica usando a conta padrão conectada ao sistema operacional por meio de um broker. Requer que o pacote @azure/identity-broker esteja instalado.	Yes

Em sua forma mais simples, você pode usar a versão sem parâmetros do 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 as Developer tool ou Deployed service credenciais, defina a variável de ambiente AZURE_TOKEN_CREDENTIALS como prod ou dev, respectivamente. Quando um valor de prod é utilizado, a cadeia de credenciais subjacente tem a seguinte aparência:

Diagrama de uma sequência de cadeia de credenciais mostrando tentativas de autenticação progredindo através de várias credenciais até que um token de acesso seja obtido.

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

Diagrama da cadeia DefaultAzureCredential com AZURE_TOKEN_CREDENTIALS definido como 'dev', mostrando as credenciais da ferramenta de desenvolvedor usadas para autenticação.

Para garantir que a variável de ambiente seja definida e definida como uma cadeia de caracteres suportada, 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 para AzureCliCredential definindo AZURE_TOKEN_CREDENTIALS como AzureCliCredential. A comparação de cadeia de caracteres é realizada 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

Importante

A AZURE_TOKEN_CREDENTIALS variável de ambiente suporta nomes de credenciais individuais nas @azure/identity versões de pacote 4.11.0 e posteriores.

Para garantir que a variável de ambiente seja definida e definida como uma cadeia de caracteres suportada, 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ê adiciona 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 por duas credenciais de desenvolvimento. AzureCliCredential é tentado primeiro, seguido de VisualStudioCodeCredential, se necessário. Em forma gráfica, a cadeia tem esta aparência:

Diagrama de uma cadeia de credenciais mostrando AzureCliCredential como a primeira tentativa e VisualStudioCodeCredential como o fallback.

Sugestão

Para melhorar o desempenho, otimize a ordenação de credenciais em ChainedTokenCredential da credencial mais para a menos usada.

Diretrizes de uso para DefaultAzureCredential

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

Aqui está o porquê:

Desafios de depuração: Quando a autenticação falha, pode ser um desafio depurar e identificar a credencial infratora. Você deve habilitar o registro 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, quando executado em uma máquina de desenvolvimento local, a identidade gerenciada não está disponível. Consequentemente, ManagedIdentityCredential falha sempre 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 na máquina host. Essas alterações aplicam-se globalmente e, portanto, alteram o comportamento de DefaultAzureCredential em tempo de execução em qualquer aplicação em execução nessa máquina.

Depurar uma credencial

Para diagnosticar um problema inesperado ou entender o que uma credencial está a fazer, ative o registo de logs no 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.

Comentários

Esta página foi útil?

Last updated on 2025-10-10