Biblioteca de clientes do Azure Identity para JavaScript – versão 4.5.0

A biblioteca de Identidade do Azure fornece autenticação de token do Microsoft Entra ID (anteriormente Azure Active Directory) por meio de um conjunto de implementações convenientes de TokenCredential.

Para obter exemplos de várias credenciais, consulte a página de exemplos de identidade do Azure .

Links de chave:

• código-fonte
• do pacote (npm)
• documentação de referência da API
• Microsoft Entra Documentação de identificação
• exemplos de

Introdução

Ambientes com suporte no momento

• versões lts do Node.js
• Versões mais recentes do Safari, Chrome, Edge e Firefox.
  • Observação: entre as diferentes credenciais exportadas nesta biblioteca, InteractiveBrowserCredential é o único com suporte no navegador.

Para obter mais informações, consulte nossa política de suporte .

Instalar o pacote

Instalar o Azure Identity com npm:

npm install --save @azure/identity

Pré-requisitos

• Uma assinatura do Azure.
• Opcional: o CLI do Azure e/ou do Azure PowerShell também pode ser útil para autenticar em um ambiente de desenvolvimento e gerenciar funções de conta.

Quando usar @azure/identity

As classes de credencial expostas por @azure/identity estão focadas em fornecer a maneira mais simples de autenticar os clientes do SDK do Azure localmente, em seus ambientes de desenvolvimento e em produção. Buscamos simplicidade e suporte razoável dos protocolos de autenticação para abranger a maioria dos cenários de autenticação possíveis no Azure. Estamos expandindo ativamente para cobrir mais cenários. Para obter uma lista completa das credenciais oferecidas, consulte a seção classes de credencial .

Todos os tipos de credencial fornecidos por @azure/identity têm suporte no Node.js. Para navegadores, InteractiveBrowserCredential é o tipo de credencial a ser usado para cenários básicos de autenticação.

A maioria dos tipos de credencial oferecidos por @azure/identity usam a biblioteca de autenticação da Microsoft para JavaScript (MSAL.js). Especificamente, usamos as bibliotecas de MSAL.js v2, que usam fluxo de código de autorização OAuth 2.0 com PKCE e são em conformidade com OpenID. Embora @azure/identity se concentre na simplicidade, as bibliotecas MSAL.js, como @azure/msal-common, @azure/msal-nodee @azure/msal-browser, foram projetadas para fornecer suporte robusto para os protocolos de autenticação aos quais o Azure dá suporte.

Quando usar outra coisa

Os tipos de credencial @azure/identity são implementações da classe TokenCredential@azure/core-auth. Em princípio, qualquer objeto com um método getToken que satisfaça getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> funciona como um TokenCredential. Isso significa que os desenvolvedores podem escrever seus próprios tipos de credencial para dar suporte a casos de autenticação não cobertos por @azure/identity. Para saber mais, consulte de Credenciais Personalizadas.

Embora nossos tipos de credencial ofereçam suporte a muitos cenários avançados, os desenvolvedores podem querer usar Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js) diretamente. Considere usar MSAL.js nos seguintes cenários:

• Desenvolvedores que desejam controle total do protocolo de autenticação e sua configuração.
• Nossos tipos de credencial foram projetados para serem usados com clientes do SDK do Azure com cache inteligente e atualização de token manipulados na camada HTTP principal. Se você tiver que usar getToken diretamente, poderá se beneficiar do uso de MSAL.js para obter mais controle sobre o fluxo de autenticação e o cache de token.

Você pode ler mais por meio dos seguintes links:

• Retratamos alguns casos de uso avançados de na página de Exemplos de Identidade do Azure .
  • Lá, temos especificamente uma seção exemplos avançados .
  • Também temos uma seção que mostra como Autenticar com a MSAL diretamente.

Para fluxos de trabalho de autenticação avançada no navegador, temos uma seção em que mostramos como usar a biblioteca de do navegador @azure/msal diretamente para autenticar clientes do SDK do Azure.

Autenticar o cliente no ambiente de desenvolvimento

Embora seja recomendável usar a identidade gerenciada em seu aplicativo hospedado no Azure, é comum que um desenvolvedor use sua própria conta para autenticar chamadas aos serviços do Azure ao depurar e executar o código localmente. Há várias ferramentas de desenvolvedor que podem ser usadas para executar essa autenticação em seu ambiente de desenvolvimento.

Autenticar por meio da CLI do Desenvolvedor do Azure

Os desenvolvedores que codificam fora de um IDE também podem usar o da CLI do Desenvolvedor do Azure para autenticar. Os aplicativos que usam o DefaultAzureCredential ou o AzureDeveloperCliCredential podem usar essa conta para autenticar chamadas em seu aplicativo ao serem executados localmente.

Para se autenticar com oda CLI do Desenvolvedor do Azure , os usuários podem executar o comando . Para usuários em execução em um sistema com um navegador da Web padrão, a CLI do Desenvolvedor do Azure inicia o navegador para autenticar o usuário.

Para sistemas sem um navegador da Web padrão, o comando azd auth login --use-device-code usa o fluxo de autenticação de código do dispositivo.

Autenticar por meio da CLI do Azure

Os aplicativos que usam o AzureCliCredential, seja diretamente ou por meio do DefaultAzureCredential, podem usar a conta da CLI do Azure para autenticar chamadas no aplicativo durante a execução local.

Para autenticar com o CLI do Azure, execute o comando az login. Para usuários em execução em um sistema com um navegador da Web padrão, a CLI do Azure inicia o navegador para autenticar o usuário.

Para sistemas sem um navegador da Web padrão, o comando az login usa o fluxo de autenticação de código do dispositivo. O usuário também pode forçar a CLI do Azure a usar o fluxo de código do dispositivo em vez de iniciar um navegador especificando o argumento --use-device-code.

Autenticar por meio do Azure PowerShell

Os aplicativos que usam o AzurePowerShellCredential, seja diretamente ou por meio do DefaultAzureCredential, podem usar a conta conectada ao Azure PowerShell para autenticar chamadas no aplicativo durante a execução local.

Para autenticar com do Azure PowerShell, execute o cmdlet Connect-AzAccount. Por padrão, como a CLI do Azure, Connect-AzAccount inicia o navegador da Web padrão para autenticar uma conta de usuário.

Se a autenticação interativa não puder ter suporte na sessão, o argumento -UseDeviceAuthentication forçará o cmdlet a usar um fluxo de autenticação de código do dispositivo, semelhante à opção correspondente na credencial da CLI do Azure.

Autenticar por meio do Visual Studio Code

Os desenvolvedores que usam o Visual Studio Code podem usar a extensão conta do Azure para autenticar por meio do editor. Os aplicativos que usam VisualStudioCodeCredential podem usar essa conta para autenticar chamadas em seu aplicativo ao serem executados localmente.

Para autenticar no Visual Studio Code, verifique se a extensão da Conta do Azure está instalada. Depois de instalado, abra o de Paleta de Comandos do e execute o comando Azure: Entrar.

Além disso, use o pacote de plug-in @azure/identity-vscode. Esse pacote fornece as dependências de VisualStudioCodeCredential e o habilita. Consulte Plug-ins.

É um problema conhecido que VisualStudioCodeCredential não funciona com versões de de extensão da Conta do Azure mais recentes do que 0.9.11. Uma correção de longo prazo para esse problema está em andamento. Enquanto isso, considere autenticação por meio da CLI do Azure.

Autenticar o cliente em navegadores

Para autenticar clientes do SDK do Azure em navegadores da Web, oferecemos o InteractiveBrowserCredential, que pode ser definido para usar redirecionamento ou pop-ups para concluir o fluxo de autenticação. É necessário criar um de Registro de Aplicativo do Azure no portal do Azure para seu aplicativo Web primeiro.

Principais conceitos

Se esta for a primeira vez que você usa @azure/identity ou a ID do Microsoft Entra, leia Usando @azure/identity com a ID do Microsoft Entra primeiro. Este documento fornece uma compreensão mais profunda da plataforma e como configurar sua conta do Azure corretamente.

Credenciais

Uma credencial é uma classe que contém ou pode obter os dados necessários para um cliente de serviço autenticar solicitações. Os clientes de serviço no SDK do Azure aceitam credenciais quando são construídos. Os clientes de serviço usam essas credenciais para autenticar solicitações no serviço.

A biblioteca de Identidade do Azure se concentra na autenticação OAuth com a ID do Microsoft Entra e oferece várias classes de credencial capazes de adquirir um token do Microsoft Entra para autenticar solicitações de serviço. Todas as classes de credencial nesta biblioteca são implementações da classe abstrata TokenCredential e qualquer uma delas pode ser usada para construir clientes de serviço capazes de autenticar com um TokenCredential.

Consulte classes de credencial.

DefaultAzureCredential

DefaultAzureCredential simplifica a autenticação ao desenvolver aplicativos que são implantados no Azure combinando credenciais usadas em ambientes de hospedagem do Azure com credenciais usadas no desenvolvimento local. Para obter mais informações, consulte Visão geral de DefaultAzureCredential.

Política de continuação

A partir da versão 3.3.0, DefaultAzureCredential tenta autenticar com todas as credenciais de desenvolvedor até que uma seja bem-sucedida, independentemente de quaisquer erros que as credenciais anteriores do desenvolvedor tenham experimentado. Por exemplo, uma credencial de desenvolvedor pode tentar obter um token e falhar, portanto, DefaultAzureCredential continua para a próxima credencial no fluxo. As credenciais de serviço implantadas interrompem o fluxo com uma exceção gerada se forem capazes de tentar a recuperação de token, mas não receberem uma.

Isso permite experimentar todas as credenciais do desenvolvedor em seu computador e ter um comportamento previsível implantado.

Observação sobre VisualStudioCodeCredential

Devido a um problema conhecido, VisualStudioCodeCredential foi removido da cadeia de tokens DefaultAzureCredential. Quando o problema for resolvido em uma versão futura, essa alteração será revertida.

Plug-ins

A Identidade do Azure para JavaScript fornece uma API de plug-in que nos permite fornecer determinadas funcionalidades por meio de pacotes de plug-in separados. O pacote @azure/identity exporta uma função de nível superior (useIdentityPlugin) que pode ser usada para habilitar um plug-in. Fornecemos dois pacotes de plug-in:

• @azure/identity-broker, que fornece suporte à autenticação agenciada por meio de um agente nativo, como o Gerenciador de Contas Web.
• @azure/identity-cache-persistence, que fornece cache de token persistente em Node.js usando um sistema de armazenamento seguro nativo fornecido pelo sistema operacional. Esse plug-in permite que os valores de access_token armazenados em cache persistam entre as sessões, o que significa que um fluxo de logon interativo não precisa ser repetido desde que um token armazenado em cache esteja disponível.

Exemplos

Você pode encontrar mais exemplos de como usar várias credenciais na página Exemplos de Identidade do Azure

Autenticar com DefaultAzureCredential

Este exemplo demonstra a autenticação do KeyClient da biblioteca de clientes @azure/keyvault-keys usando DefaultAzureCredential.

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure vault URL
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();
// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

Especificar uma identidade gerenciada atribuída pelo usuário com DefaultAzureCredential

Um cenário relativamente comum envolve a autenticação usando uma identidade gerenciada atribuída pelo usuário para um recurso do Azure. Explore o exemplo de na Autenticação de uma identidade gerenciada atribuída pelo usuário com DefaultAzureCredential para ver como isso é feito em uma tarefa relativamente simples que pode ser configurada usando variáveis de ambiente ou em código.

Definir um fluxo de autenticação personalizado com ChainedTokenCredential

Embora DefaultAzureCredential geralmente seja a maneira mais rápida de começar a desenvolver aplicativos para o Azure, os usuários mais avançados podem querer personalizar as credenciais consideradas durante a autenticação. O ChainedTokenCredential permite que os usuários combinem várias instâncias de credencial para definir uma cadeia personalizada de credenciais. Este exemplo demonstra a criação de um ChainedTokenCredential que tenta autenticar usando duas instâncias configuradas de ClientSecretCredential, para autenticar o KeyClient do @azure/keyvault-keys:

import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure variables
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
const tenantId = "<tenant-id>";
const clientId = "<client-id>";
const clientSecret = "<client-secret>";
const anotherClientId = "<another-client-id>";
const anotherSecret = "<another-client-secret>";
// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);
// The chain can be used anywhere a credential is required
const client = new KeyClient(vaultUrl, credentialChain);

Suporte à identidade gerenciada

O de autenticação de identidade gerenciada tem suporte por meio do DefaultAzureCredential ou das classes de credencial ManagedIdentityCredential diretamente para os seguintes serviços do Azure:

• Serviço de Aplicativo do Azure e do Azure Functions
• do Azure Arc
• Azure Cloud Shell
• do Serviço de Kubernetes do Azure
• Azure Service Fabric
• Máquinas Virtuais do Azure
• conjuntos de dimensionamento de máquinas virtuais do Azure

Para obter exemplos de como usar a identidade gerenciada para autenticação, consulte os exemplos.

Configuração de nuvem

Credenciais padrão para autenticação no ponto de extremidade do Microsoft Entra para a Nuvem Pública do Azure. Para acessar recursos em outras nuvens, como o Azure Governamental ou uma nuvem privada, configure credenciais com o argumento authorityHost no construtor. A enumeração AzureAuthorityHosts define as autoridades para nuvens conhecidas. Para a nuvem do governo dos EUA, você pode criar uma credencial desta maneira:

import { ClientSecretCredential, AzureAuthorityHosts } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  },
);

Como alternativa para especificar o argumento authorityHost, você também pode definir a variável de ambiente AZURE_AUTHORITY_HOST para a URL da autoridade da nuvem. Essa abordagem é útil ao configurar várias credenciais para autenticar na mesma nuvem ou quando o ambiente implantado precisa definir a nuvem de destino:

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

A enumeração AzureAuthorityHosts define as autoridades para nuvens conhecidas para sua conveniência; no entanto, se a autoridade para sua nuvem não estiver listada em AzureAuthorityHosts, você poderá passar qualquer URL de autoridade válida como um argumento de cadeia de caracteres. Por exemplo:

import { ClientSecretCredential } from "@azure/identity";

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: "https://login.partner.microsoftonline.cn",
  },
);

Nem todas as credenciais exigem essa configuração. As credenciais que se autenticam por meio de uma ferramenta de desenvolvimento, como AzureCliCredential, usam a configuração dessa ferramenta. Da mesma forma, VisualStudioCodeCredential aceita um argumento authorityHost, mas usa como padrão o authorityHost configuração Azure: Cloud do Visual Studio Code correspondente.

Classes de credencial

Cadeias de credenciais

Credencial	Uso	Exemplo
DefaultAzureCredential	Fornece uma experiência de autenticação simplificada para iniciar rapidamente o desenvolvimento de aplicativos executados no Azure.	exemplo
ChainedTokenCredential	Permite que os usuários definam fluxos de autenticação personalizados compondo várias credenciais.	exemplo

Autenticar aplicativos hospedados no Azure

Credencial	Uso	Exemplo
EnvironmentCredential	Autentica uma entidade de serviço ou um usuário por meio de informações de credencial especificadas em variáveis de ambiente.	exemplo
ManagedIdentityCredential	Autentica a identidade gerenciada de um recurso do Azure.	exemplo
WorkloadIdentityCredential	Dá suporte de ID de Carga de Trabalho do Microsoft Entra no Kubernetes.	exemplo

Autenticar entidades de serviço

Credencial	Uso	Exemplo	Referência
AzurePipelinesCredential	Dá suporte de ID de Carga de Trabalho do Microsoft Entra no Azure Pipelines.	exemplo
ClientAssertionCredential	Autentica uma entidade de serviço usando uma declaração de cliente assinada.	exemplo	de autenticação da entidade de serviço
ClientCertificateCredential	Autentica uma entidade de serviço usando um certificado.	exemplo	de autenticação da entidade de serviço
ClientSecretCredential	Autentica uma entidade de serviço usando um segredo.	exemplo	de autenticação da entidade de serviço

Autenticar usuários

Credencial	Uso	Exemplo	Referência
AuthorizationCodeCredential	Autentica um usuário com um código de autorização obtido anteriormente.	exemplo	código de autenticação OAuth2
DeviceCodeCredential	Autentica interativamente um usuário em dispositivos com interface do usuário limitada.	exemplo	de autenticação de código do dispositivo
InteractiveBrowserCredential	Autentica interativamente um usuário com o navegador do sistema padrão. Leia mais sobre como isso acontece aqui.	exemplo	código de autenticação OAuth2
OnBehalfOfCredential	Propaga a identidade do usuário delegado e as permissões por meio da cadeia de solicitações		de autenticação em nome de
UsernamePasswordCredential	Autentica um usuário com um nome de usuário e senha.	exemplo	de autenticação de nome de usuário + senha

Autenticar por meio de ferramentas de desenvolvimento

Credencial	Uso	Exemplo	Referência
AzureCliCredential	Autenticar em um ambiente de desenvolvimento com a CLI do Azure.	exemplo	de autenticação da CLI do Azure
AzureDeveloperCliCredential	Autentique-se em um ambiente de desenvolvimento com o usuário ou a entidade de serviço habilitada na CLI do Desenvolvedor do Azure.		de referência da CLI do Desenvolvedor do Azure
AzurePowerShellCredential	Autenticar em um ambiente de desenvolvimento usando o Azure PowerShell.	exemplo	autenticação do Azure PowerShell
VisualStudioCodeCredential	Autentica-se como o usuário conectado à extensão da Conta do Azure do Visual Studio Code.		de extensão da Conta do Azure do VS Code

Variáveis de ambiente

DefaultAzureCredential e EnvironmentCredential podem ser configurados com variáveis de ambiente. Cada tipo de autenticação requer valores para variáveis específicas.

Entidade de serviço com segredo

Nome da variável	Valor
AZURE_CLIENT_ID	ID de um aplicativo do Microsoft Entra
AZURE_TENANT_ID	ID do locatário do Microsoft Entra do aplicativo
AZURE_CLIENT_SECRET	um dos segredos do cliente do aplicativo

Entidade de serviço com certificado

Nome da variável	Valor
AZURE_CLIENT_ID	ID de um aplicativo do Microsoft Entra
AZURE_TENANT_ID	ID do locatário do Microsoft Entra do aplicativo
AZURE_CLIENT_CERTIFICATE_PATH	caminho para um arquivo de certificado codificado em PEM, incluindo chave privada
AZURE_CLIENT_CERTIFICATE_PASSWORD	Senha (opcional) do arquivo de certificado, se houver
AZURE_CLIENT_SEND_CERTIFICATE_CHAIN	(opcional) enviar cadeia de certificados no cabeçalho x5c para dar suporte ao nome da entidade/autenticação baseada em emissor

Nome de usuário e senha

Nome da variável	Valor
AZURE_CLIENT_ID	ID de um aplicativo do Microsoft Entra
AZURE_TENANT_ID	ID do locatário do Microsoft Entra do aplicativo
AZURE_USERNAME	um nome de usuário (geralmente um endereço de email)
AZURE_PASSWORD	senha do usuário

A configuração é tentada na ordem anterior. Por exemplo, se os valores para um segredo do cliente e um certificado estiverem presentes, o segredo do cliente será usado.

Avaliação contínua de acesso

A partir da versão 3.3.0, o acesso a recursos protegidos por CAE ( de Avaliação de Acesso Contínuo) é possível por solicitação. Isso pode ser habilitado usando a API GetTokenOptions.enableCae(boolean). O CAE não tem suporte para credenciais de desenvolvedor.

Cache de token

O cache de tokens é um recurso fornecido pela biblioteca de Identidade do Azure que permite que os aplicativos:

• Tokens de cache na memória (padrão) e no disco (aceitação).
• Melhorar a resiliência e o desempenho.
• Reduza o número de solicitações feitas à ID do Microsoft Entra para obter tokens de acesso.

A biblioteca de Identidades do Azure oferece cache de disco persistente e na memória. Para obter mais informações, consulte a documentação de cache do token .

Autenticação agenciada

Um agente de autenticação é um aplicativo que é executado no computador de um usuário e gerencia os handshakes de autenticação e a manutenção de token para contas conectadas. Atualmente, há suporte apenas para o WAM (Gerenciador de Contas Web do Windows). Para habilitar o suporte, use o pacote @azure/identity-broker. Para obter detalhes sobre como autenticar usando o WAM, consulte a documentação do plug-in do agente.

Solucionando problemas

Para obter assistência com a solução de problemas, consulte o guia de solução de problemas .

Próximas etapas

Ler a documentação

A documentação da API para essa biblioteca pode ser encontrada em nosso site de documentação .

Suporte à biblioteca de clientes

Bibliotecas de cliente e gerenciamento listadas na página de versões do SDK do do Azure que dão suporte à autenticação do Microsoft Entra aceitam credenciais dessa biblioteca. Saiba mais sobre como usar essas bibliotecas em sua documentação, que está vinculada na página de versões.

Problemas conhecidos

Suporte ao Azure AD B2C

Essa biblioteca não dá suporte ao serviço de Azure AD B2C.

Para obter outros problemas abertos, consulte odo repositório github da biblioteca.

Fornecer comentários

Se você encontrar bugs ou tiver sugestões, abrir um problema.

Contribuindo

Para contribuir com essa biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

impressões