Cadeias de credenciais na biblioteca de clientes da Identidade do Azure para JavaScript

A biblioteca de clientes da Identidade do Azure fornece credenciais, as quais são 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 selecionadas individualmente ou encadeadas para formar uma sequência ordenada de mecanismos de autenticação a serem tentados.

• Credenciais individuais proporcionam certeza e velocidade. Se eles falharem, você saberá que a credencial não foi autenticada.
• Cadeias fornecem alternativas. Quando a credencial falha ao autenticar, a próxima credencial na cadeia é utilizada.

Projetar seus fluxos de autenticação

Quando você usa bibliotecas de clientes do SDK do Azure, a primeira etapa é autenticar no Azure. Há muitas opções de como autenticar para considerar, como ferramentas e IDEs usadas na equipe de desenvolvimento, fluxos de trabalho de automação, como teste e CI/CD, e plataformas de hospedagem, como o Serviço de Aplicativo do Azure.

Escolha entre as seguintes progressões comuns para o fluxo de autenticação:

• Use o DefaultAzureCredential para equipes de cujos desenvolvedores usam vários IDEs e CLIs para autenticar no Azure. Isso permite a maior flexibilidade. Essa flexibilidade é fornecida à custa do desempenho para validar as credenciais na cadeia até que uma delas seja validada com sucesso.

  • O fallback de credencial para credencial é selecionado em seu nome com base no ambiente detectado.
  • Para determinar qual credencial foi selecionada, ative a depuração.

• Use o ChainedTokenCredential para equipes que possuem uma seleção de ferramentas rigorosa e bem definida. Por exemplo, todos eles se autenticam e usam o mesmo IDE ou CLI. Isso permite que a equipe selecione as credenciais exatas e a ordem que ainda fornece flexibilidade, mas com um custo de desempenho reduzido.

  • Você seleciona o caminho de fallback de uma credencial para outra, independentemente do ambiente em que o caminho é executado.
  • Para determinar qual credencial foi selecionada, ative a depuração.

• Para equipes com credenciais garantidas em todos os ambientes, uma instrução de controle de fluxo como "if/else" permite saber qual credencial foi escolhida em cada ambiente.

  • Não há alternativa para outro tipo de credencial.
  • Você não precisa fazer depuração para determinar qual credencial foi escolhida porque ela foi especificada.

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:

Usar DefaultAzureCredential para flexibilidade

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.

Pedido	Credencial	Descrição
1	Ambiente.	Lê uma coleção de variáveis de ambiente para determinar se uma entidade de serviço de aplicativo (usuário do aplicativo) está configurada para o aplicativo. Nesse caso, DefaultAzureCredential usa esses valores para autenticar o aplicativo no Azure. Esse método geralmente é usado em ambientes de servidor, mas também pode ser usado ao desenvolver localmente.
2	Identidade de carga de trabalho	Se o aplicativo for implantado em um host do Azure com a Identidade de Carga de Trabalho habilitada, autentique essa conta.
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.
4	CLI do Azure	Se o desenvolvedor tiver sido autenticado no Azure usando o comando az login da CLI do Azure, autentique o aplicativo no Azure usando essa mesma conta.
5	Azure PowerShell	Se o desenvolvedor tiver sido autenticado no Azure usando o cmdlet Connect-AzAccount do Azure PowerShell, autentique o aplicativo no Azure usando essa mesma conta.
6	CLI do Desenvolvedor do Azure	Se o desenvolvedor tiver sido autenticado no Azure usando o comando azd auth login da CLI do Desenvolvedor do Azure, autentique-se com essa conta.

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://<my_account_name>.blob.core.windows.net",
    credential
);

As credenciais são globais no contexto do ambiente

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.

Utilize ChainedTokenCredential para obter maior granularidade

ChainedTokenCredential é uma cadeia vazia à qual você pode adicionar credenciais para atender às necessidades do seu aplicativo. Por exemplo, o exemplo a seguir adiciona uma instância de ManagedIdentityCredential e, em seguida, uma instância de AzureCliCredential.

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

const credential = ChainedTokenCredential(
    ManagedIdentityCredential({ clientId: "<YOUR_CLIENT_ID>" }),
    AzureCliCredential()
);

O exemplo de código anterior cria uma cadeia de credenciais personalizada composta por duas credenciais. A variante de identidade gerenciada atribuída pelo usuário de ManagedIdentityCredential é tentada primeiro, seguida por AzureCliCredential, se necessário. Na forma gráfica, a cadeia tem esta aparência:

Dica

Para melhorar o desempenho, otimize a ordenação de credenciais para seu ambiente de produção . As credenciais destinadas ao uso no ambiente de desenvolvimento local devem ser adicionadas por último.

Depurar uma credencial encadeada

Para depurar uma cadeia de credenciais, habilite o registro em log do Azure SDK.

Mais recursos

• CLI do Azure