Biblioteca de clientes da Identidade do Azure para JavaScript – versão 4.2.0
A biblioteca de Identidade do Azure fornece Microsoft Entra ID autenticação de token (anteriormente Azure Active Directory) por meio de um conjunto de implementações de TokenCredential convenientes.
Para obter exemplos de várias credenciais, consulte a página Exemplos de Identidade do Azure.
Links principais:
- Código-fonte
- Pacote (npm)
- Documentação de referência da API
- Documentação do Microsoft Entra ID
- Amostras
Introdução
Migrar da v1 para a v2 de @azure/identity
Se você estiver usando a v1 do , consulte o guia de @azure/identitymigração para atualizar para v2.
Ambientes com suporte no momento
- Versões LTS do Node.js
- Nota: Se o aplicativo for executado no Node.js v8 ou inferior e você não puder atualizar sua versão Node.js para a versão estável mais recente, fixe sua
@azure/identitydependência na versão 1.1.0.
- Nota: Se o aplicativo for executado no Node.js v8 ou inferior e você não puder atualizar sua versão Node.js para a versão estável mais recente, fixe sua
- Versões mais recentes do Safari, Chrome, Edge e Firefox.
- Observação: entre as diferentes credenciais exportadas nesta biblioteca,
InteractiveBrowserCredentialestá a única que tem suporte no navegador.
- Observação: entre as diferentes credenciais exportadas nesta biblioteca,
Confira nossa política de suporte para mais detalhes.
Instalar o pacote
Instale o Azure Identity com npm:
npm install --save @azure/identity
Pré-requisitos
- Uma assinatura do Azure.
- Opcional: a CLI do Azure e/ou Azure PowerShell também podem ser úteis 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 se concentram em fornecer a maneira mais simples de autenticar os clientes do SDK do Azure localmente, em seus ambientes de desenvolvimento e em produção. Nosso objetivo é a simplicidade e o suporte razoável dos protocolos de autenticação para abranger a maioria dos cenários de autenticação possíveis no Azure. Estamos nos 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 são compatíveis com 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 pelo @azure/identity usam a Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js). Especificamente, usamos as bibliotecas de MSAL.js v2, que usam o Fluxo de Código de Autorização do OAuth 2.0 com PKCE e são compatíveis com OpenID. Embora @azure/identity se concentre na simplicidade, as bibliotecas MSAL.js, como @azure/msal-common, @azure/msal-node e @azure/msal-browser, foram projetadas para fornecer suporte robusto para os protocolos de autenticação compatíveis com o Azure.
Quando usar outra coisa
Os @azure/identity tipos de credencial são implementações da classe @azure/core-authTokenCredential. Em princípio, qualquer objeto com um getToken método que satisfaça getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> funcionará 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, confira Credenciais Personalizadas.
Embora nossos tipos de credencial ofereçam suporte a muitos casos avançados, os desenvolvedores podem querer ter controle total do protocolo de autenticação. Para esse caso de uso, recomendamos usar a Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js) diretamente. Você pode ler mais por meio dos seguintes links:
- Retratamos alguns casos de uso avançados de na página Exemplos de
@azure/identityIdentidade 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 @azure/msal-browser diretamente para autenticar clientes do SDK do Azure.
Autenticar o cliente no ambiente de desenvolvimento
Embora seja recomendável usar a autenticação de identidade gerenciada ou de entidade de serviço no aplicativo de produção, é comum que um desenvolvedor use a própria conta para autenticar chamadas aos serviços do Azure ao depurar e executar código localmente. Há várias ferramentas de desenvolvedor que podem ser usadas para executar essa autenticação no ambiente de desenvolvimento.
Autenticar por meio do Azure Developer CLI
Os desenvolvedores que codificam fora de um IDE também podem usar o [Azure Developer CLI][azure_developer_cli] para autenticar. Os aplicativos que usam DefaultAzureCredential ou AzureDeveloperCliCredential podem usar essa conta para autenticar chamadas no aplicativo ao serem executados localmente.
Para autenticar com o [Azure Developer CLI][azure_developer_cli], os usuários podem executar o comando azd auth login. Para usuários em execução em um sistema com um navegador da Web padrão, o Azure Developer CLI iniciará o navegador para autenticar o usuário.
Para sistemas sem um navegador da Web padrão, o comando azd auth login --use-device-code usará 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 ao executar localmente.
Para fazer a autenticação com a CLI do Azure, os usuários podem executar o comando az login. Para usuários com execução em um sistema com um navegador da Web padrão, a CLI do Azure iniciará o navegador para autenticar o usuário.
Para sistemas sem um navegador da Web padrão, o comando az login usará 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 de Azure PowerShell
Os aplicativos que usam o AzurePowerShellCredential, seja diretamente ou por meio do DefaultAzureCredential, podem usar a conta conectada a Azure PowerShell para autenticar chamadas no aplicativo ao executar localmente.
Para autenticar com Azure PowerShell os usuários podem executar o Connect-AzAccount cmdlet. Por padrão, a CLI Connect-AzAccount do Azure iniciará 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 -UseDeviceAuthentication argumento 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 de Visual Studio Code
Os desenvolvedores que usam 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 em Visual Studio Code, verifique se a extensão da Conta do Azure está instalada. Depois de instalado, abra a Paleta de Comandos e execute o comando Azure: Entrar .
Além disso, use o pacote de @azure/identity-vscode plug-in. 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 extensão da Conta do Azure mais recentes do que a 0.9.11. Uma correção de longo prazo para esse problema está em andamento. Enquanto isso, considere a 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 o redirecionamento ou pop-ups para concluir o fluxo de autenticação. É necessário criar um registro de Azure App no portal do Azure para seu aplicativo Web primeiro.
Principais conceitos
Se esta for a primeira vez que você usa @azure/identity ou Microsoft Entra ID, leia Usar @azure/identity com Microsoft Entra ID 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 para o serviço.
A biblioteca de Identidade do Azure se concentra na autenticação OAuth com Microsoft Entra ID e oferece uma variedade de classes de credencial capazes de adquirir um token de Microsoft Entra para autenticar solicitações de serviço. Todas as classes de credenciais nesta biblioteca são implementações da classe abstrata TokenCredential e todas elas podem ser usadas por clientes do serviço de construtor que tenham capacidade de autenticação com um TokenCredential.
Confira Classes de credencial.
DefaultAzureCredential
O DefaultAzureCredential é apropriado para a maioria dos cenários em que o aplicativo se destina a ser executado no Azure. Isso ocorre porque o DefaultAzureCredential combina credenciais comumente usadas para autenticar quando implantadas com credenciais usadas para autenticar em um ambiente de desenvolvimento.
Observação:
DefaultAzureCredentialdestina-se a simplificar a introdução ao SDK manipulando cenários comuns com comportamentos padrão razoáveis. Os desenvolvedores que desejam mais controle ou cujo cenário não é abordado nas configurações padrão devem usar outros tipos de credencial.
Se usado de Node.js, o DefaultAzureCredential tentará autenticar por meio dos seguintes mecanismos na ordem:
- Ambiente – o
DefaultAzureCredentiallerá as informações da conta especificadas por meio de variáveis de ambiente e as usará para autenticar. - Identidade da carga de trabalho – se o aplicativo for implantado para Serviço de Kubernetes do Azure com a Identidade Gerenciada habilitada,
DefaultAzureCredentialserá autenticada com ela. - Identidade Gerenciada – se o aplicativo for implantado em um host do Azure com a Identidade Gerenciada habilitada, o
DefaultAzureCredentialserá autenticado com essa conta. - CLI do Azure – se o desenvolvedor tiver autenticado uma conta por meio do comando da CLI
az logindo Azure, oDefaultAzureCredentialserá autenticado com essa conta. - Azure PowerShell – se o desenvolvedor tiver se autenticado usando o comando do módulo
Connect-AzAccountAzure PowerShell, oDefaultAzureCredentialserá autenticado com essa conta. - Azure Developer CLI – se o desenvolvedor tiver autenticado uma conta por meio do comando Azure Developer CLI
azd auth login, oDefaultAzureCredentialserá autenticado com essa conta.
Política de continuação
A partir da versão 3.3.0, DefaultAzureCredential tentará autenticar com todas as credenciais de desenvolvedor até que uma seja bem-sucedida, independentemente de quaisquer erros que as credenciais anteriores do desenvolvedor tenham sofrido. Por exemplo, uma credencial de desenvolvedor pode tentar obter um token e falhar, portanto DefaultAzureCredential , continuará para a próxima credencial no fluxo. As credenciais de serviço implantadas interromperão o fluxo com uma exceção gerada se puderem tentar recuperar o token, mas não receberem uma.
Isso permite experimentar todas as credenciais do desenvolvedor em seu computador, ao mesmo tempo em que tem um comportamento previsível implantado.
Observação sobre VisualStudioCodeCredential
Devido a um problema conhecido, VisualStudioCodeCredential foi removido da DefaultAzureCredential cadeia de tokens. 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 @azure/identity pacote 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 armazenadosaccess_tokenem cache persistam entre as sessões, o que significa que um fluxo de logon interativo não precisa ser repetido enquanto um token armazenado em cache estiver disponível.
Exemplos
Veja mais exemplos de uso de várias credenciais na página de exemplos do Azure Identity
Autenticar com o DefaultAzureCredential
Este exemplo demonstra a autenticação do KeyClient da biblioteca de clientes @azure/keyvault-keys usando o DefaultAzureCredential.
// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.
// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";
// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";
// 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 o 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 sobre Como autenticar uma identidade gerenciada atribuída pelo usuário com DefaultAzureCredential para ver como isso se torna 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 seja geralmente a maneira mais rápida de começar a desenvolver aplicativos para o Azure, os usuários mais avançados podem personalizar as credenciais consideradas durante a autenticaçã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 tentará se autenticar usando duas instâncias configuradas de forma diferente de ClientSecretCredential, para autenticar a KeyClient do @azure/keyvault-keys:
import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
// 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
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);
Suporte de identidade gerenciada
A autenticação de identidade gerenciada tem suporte por meio das DefaultAzureCredential classes de credencial ou ManagedIdentityCredential diretamente para os seguintes serviços do Azure:
- Serviço de Aplicativo do Azure e Azure Functions
- Azure Arc
- Azure Cloud Shell
- 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
As credenciais são padrão para autenticação no ponto de extremidade Microsoft Entra para a Nuvem Pública do Azure. Para acessar recursos em outras nuvens, como Azure Governamental ou uma nuvem privada, configure as credenciais com o authorityHost argumento no construtor. A AzureAuthorityHosts interface define as autoridades para nuvens conhecidas. Para a nuvem do governo dos EUA, você pode instanciar uma credencial dessa forma:
import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
"<YOUR_TENANT_ID>",
"<YOUR_CLIENT_ID>",
"<YOUR_CLIENT_SECRET>",
{
authorityHost: AzureAuthorityHosts.AzureGovernment,
}
);
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, aceita um authorityHost argumento, VisualStudioCodeCredential mas usa como padrão a authorityHost configuração do Azure: Cloud do Visual Studio Code correspondente.
Classes de credencial
Autenticar aplicativos hospedados no Azure
| Credencial | Uso | Exemplo |
|---|---|---|
DefaultAzureCredential |
Fornece uma experiência de autenticação simplificada para iniciar rapidamente o desenvolvimento de aplicativos executados no Azure. | Exemplo |
ChainedTokenCredential |
Permita que os usuários definam fluxos de autenticação personalizados compondo várias credenciais. | 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 a ID de carga de trabalho do Microsoft Entra no Kubernetes. | Exemplo |
Autenticar entidades de serviço
| Credencial | Uso | Exemplo | Referência |
|---|---|---|---|
ClientAssertionCredential |
Autentica uma entidade de serviço usando uma declaração de cliente assinada. | Exemplo | Autenticação de entidade de serviço |
ClientCertificateCredential |
Autentica uma entidade de serviço usando um certificado. | Exemplo | Autenticação de entidade de serviço |
ClientSecretCredential |
Autentica uma entidade de serviço usando um segredo. | Exemplo | Autenticação de 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 do OAuth2 |
DeviceCodeCredential |
Autentica de modo interativo um usuário em dispositivos com interface do usuário limitada. | Exemplo | Autenticação de código de dispositivo |
InteractiveBrowserCredential |
Autentica interativamente um usuário com o navegador padrão do sistema. Leia mais aqui para saber como isso ocorre. | Exemplo | Código de autenticação do OAuth2 |
OnBehalfOfCredential |
Propaga a identidade do usuário delegado e as permissões por meio da cadeia de solicitações | Autenticação em nome do usuário | |
UsernamePasswordCredential |
Autentica um usuário com um nome de usuário e uma senha. | Exemplo | Autenticação de nome de usuário e senha |
Autenticar por meio de ferramentas de desenvolvimento
| Credencial | Uso | Exemplo | Referência |
|---|---|---|---|
AzureCliCredential |
Fazer a autenticação em um ambiente de desenvolvimento com a CLI do Azure. | Exemplo | Autenticação com a CLI do Azure |
AzureDeveloperCliCredential |
Autentique-se em um ambiente de desenvolvimento com o usuário ou a entidade de serviço habilitado no Azure Developer CLI. | Referência de Azure Developer CLI | |
AzurePowerShellCredential |
Autentique-se em um ambiente de desenvolvimento usando Azure PowerShell. | Exemplo | autenticação Azure PowerShell |
VisualStudioCodeCredential |
Autentica como o usuário entrou na extensão de conta do Visual Studio Code Azure. | 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 Microsoft Entra |
AZURE_TENANT_ID |
ID do locatário 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 Microsoft Entra |
AZURE_TENANT_ID |
ID do locatário 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 do arquivo de certificado, se houver |
Nome de usuário e senha
| Nome da variável | Valor |
|---|---|
AZURE_CLIENT_ID |
ID de um aplicativo Microsoft Entra |
AZURE_TENANT_ID |
ID do locatário Microsoft Entra do aplicativo |
AZURE_USERNAME |
um nome de usuário (geralmente um endereço de email) |
AZURE_PASSWORD |
a senha desse usuário |
A configuração é tentada na ordem acima. 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 aos recursos protegidos pela CAE ( Avaliação Contínua de Acesso ) é possível por solicitação. Isso pode ser habilitado usando a GetTokenOptions.enableCae(boolean) API. Não há suporte para CAE para credenciais de desenvolvedor.
Armazenamento de token em cache
O cache de tokens é um recurso fornecido pela biblioteca de Identidade do Azure que permite que os aplicativos:
- Cache de tokens 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 a Microsoft Entra ID para obter tokens de acesso.
A biblioteca de Identidade do Azure oferece cache de disco persistente e na memória. Para obter mais detalhes, consulte a documentação de cache de 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 @azure/identity-broker pacote. Para obter detalhes sobre como autenticar usando o WAM, consulte a documentação do plug-in do agente.
Solução de problemas
Para obter assistência com a solução de problemas, consulte o guia de solução de problemas.
Próximas etapas
Leia a documentação
A documentação da API dessa biblioteca pode ser encontrada no site da documentação.
Suporte da biblioteca de clientes
Bibliotecas de cliente e gerenciamento listadas na página versões do SDK do Azure que dão suporte a Microsoft Entra autenticação 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 do Azure AD B2C
Essa biblioteca não dá suporte ao serviço Azure AD B2C.
Para outros problemas abertos, consulte o repositório GitHub da biblioteca.
Fornecer comentários
Se você encontrar bugs ou tiver sugestões, abra um problema.
Contribuição
Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.
Azure SDK for JavaScript
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de