Biblioteca de cliente do Azure Identity para JavaScript - versão 4.4.1

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

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

Ligações principais:

• Código fonte
• Pacote (npm)
• de documentação de referência da API
• documentação do Microsoft Entra ID
• Amostras

Primeiros passos

Ambientes atualmente suportados

• versões LTS do Node.js
  • Nota: Se o seu aplicativo for executado em 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 dependência @azure/identity na versão 1.1.0.
• Versões mais recentes do Safari, Chrome, Edge e Firefox.
  • Nota: Entre as diferentes credenciais exportadas nesta biblioteca, InteractiveBrowserCredential é a única suportada no navegador.

Consulte o nosso de política de suporte para obter mais detalhes.

Instalar o pacote

Instale o Azure Identity com npm:

npm install --save @azure/identity

Pré-requisitos

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

Quando usar @azure/identity

As classes de credenciais expostas pelo @azure/identity se concentram em fornecer a maneira mais direta 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 cobrir 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 credenciais.

Todos os tipos de credenciais fornecidos pelo @azure/identity são suportados no Node.js. Para navegadores, InteractiveBrowserCredential é o tipo de credencial a ser usado para cenários de autenticação básica.

A maioria dos tipos de credenciais oferecidos pelo @azure/identity usam o Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js). Especificamente, usamos as bibliotecas de MSAL.js v2, que usam OAuth 2.0 Authorization Code Flow com PKCE e são compatíveis com OpenID. Embora se concentre na simplicidade, as bibliotecas MSAL.js, comocomum @azure/msal,de nó @azure/msal enavegador @azure/msal, são projetadas para fornecer suporte robusto para os protocolos de autenticação suportados pelo Azure.

Quando usar outra coisa

Os @azure/identity tipos de credenciais são implementações da classe TokenCredential do @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> funcionará como um TokenCredential. Isso significa que os desenvolvedores podem escrever seus próprios tipos de credenciais para dar suporte a casos de autenticação não cobertos pelo @azure/identity. Para saber mais, consulte Credenciais personalizadas.

Embora nossos tipos de credenciais ofereçam suporte a muitos casos avançados, os desenvolvedores podem querer controle total do protocolo de autenticação. Para esse caso de uso, recomendamos usar Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js) diretamente. Você pode ler mais através dos seguintes links:

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

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

Autenticar o cliente no ambiente de desenvolvimento

Embora recomendemos o uso da identidade gerenciada em seu aplicativo hospedado no Azure, é comum que um desenvolvedor use sua própria conta para autenticar chamadas para serviços do Azure ao depurar e executar código localmente. Existem 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 quando executados localmente.

Para autenticar com a CLI do Azure Developer, 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, a CLI do Desenvolvedor do Azure 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 do 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 quando executados localmente.

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

de início de sessão da conta da CLI do Azure

Para sistemas sem um navegador da Web padrão, o comando az login usará o fluxo de autenticação do 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.

de início de sessão do código de dispositivo da conta da CLI do Azure

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 quando executadas localmente.

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

de início de sessão da Conta do Azure PowerShell

Se a autenticação interativa não puder ser suportada na sessão, o argumento -UseDeviceAuthentication forçará o cmdlet a usar um fluxo de autenticação de código de dispositivo em vez disso, 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 o de extensão de Conta do Azure para autenticar por meio do editor. Os aplicativos que usam VisualStudioCodeCredential podem usar essa conta para autenticar chamadas em seus aplicativos quando executados localmente.

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

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

É um problema conhecido que VisualStudioCodeCredential não funciona com extensão de Conta do Azure versões mais recentes que 0.9.11. Uma solução de longo prazo para este problema está em andamento. Enquanto isso, considere autenticar 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 configurado 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.

Conceitos-chave

Se esta for a primeira vez que você usa o @azure/identity ou o Microsoft Entra ID, leia Usando o @azure/identity com o 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 a ID do Microsoft Entra e oferece uma variedade de classes de credenciais capazes de adquirir um token do Microsoft Entra para autenticar solicitações de serviço. Todas as classes de credenciais nesta biblioteca são implementações do TokenCredential classe abstrata, e qualquer uma delas pode ser usada para construir clientes de serviço capazes de autenticar com um TokenCredential.

Consulte Classes de credenciais.

DefaultAzureCredential

O DefaultAzureCredential é apropriado para a maioria dos cenários em que o aplicativo deve ser executado no Azure. Isso ocorre porque o DefaultAzureCredential combina credenciais comumente usadas para autenticar quando implantado com credenciais usadas para autenticar em um ambiente de desenvolvimento.

Nota: DefaultAzureCredential destina-se a simplificar a introdução ao SDK ao lidar com cenários comuns com comportamentos padrão razoáveis. Os desenvolvedores que desejam mais controle ou cujo cenário não é atendido pelas configurações padrão devem usar outros tipos de credenciais.

Se usado a partir de Node.js, o DefaultAzureCredential tentará autenticar através dos seguintes mecanismos, na ordem:

1. Environment - O DefaultAzureCredential lerá as informações da conta especificadas por meio variáveis de ambiente e as usará para autenticar.
2. Workload Identity - Se o aplicativo for implantado no Serviço Kubernetes do Azure com a Identidade Gerenciada habilitada, DefaultAzureCredential será autenticado com ele.
3. de Identidade Gerenciada - Se o aplicativo for implantado em um host do Azure com a Identidade Gerenciada habilitada, o DefaultAzureCredential será autenticado com essa conta.
4. da CLI do Azure - Se o desenvolvedor tiver autenticado uma conta por meio do comando az login da CLI do Azure, o DefaultAzureCredential será autenticado com essa conta.
5. do Azure PowerShell - Se o desenvolvedor tiver autenticado usando o comando Connect-AzAccount módulo do Azure PowerShell, o DefaultAzureCredential será autenticado com essa conta.
6. da CLI do Desenvolvedor do Azure - Se o desenvolvedor tiver autenticado uma conta por meio do comando azd auth login da CLI do Desenvolvedor do Azure, o DefaultAzureCredential será 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 de desenvolvedor anteriores tenham experimentado. 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 lançada se puderem tentar a recuperação de tokens, mas não receberem uma.

Isso permite experimentar todas as credenciais de desenvolvedor em sua máquina enquanto tem um comportamento de implantação previsível.

Nota 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

O Azure Identity for 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 ativar um plugin. Nós fornecemos dois pacotes de plugins:

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

Exemplos

Você pode encontrar mais exemplos de uso de várias credenciais na Página Exemplos de Identidade do Azure

Autenticar com o DefaultAzureCredential

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

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

Especifique 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 em Autenticando 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.

Defina um fluxo de autenticação personalizado com o ChainedTokenCredential

Embora o DefaultAzureCredential seja geralmente 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 ao autenticar. O ChainedTokenCredential permite que os usuários combinem várias instâncias de credenciais para definir uma cadeia personalizada de credenciais. Este exemplo demonstra a criação de um que tentará autenticar usando duas instâncias configuradas de forma diferente do e, em seguida, autenticar o a partir 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 gerenciado

O de autenticação de identidade Managed tem suporte por meio das classes de credenciais ou diretamente para os seguintes serviços do Azure:

• Serviço de Aplicativo do Azure e Azure Functions
• Azure Arc
• Azure Cloud Shell
• Serviço 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 na nuvem

As 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 Government ou uma nuvem privada, configure as credenciais com o argumento authorityHost no construtor. A interface AzureAuthorityHosts define autoridades para nuvens bem conhecidas. Para a nuvem do governo dos EUA, você pode instanciar uma credencial desta maneira:

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 autenticadas por meio de uma ferramenta de desenvolvimento, como AzureCliCredential, usam a configuração dessa ferramenta. Da mesma forma, VisualStudioCodeCredential aceita um argumento authorityHost, mas assume como padrão a configuração authorityHost correspondente do Visual Studio Code Azure: Cloud.

Classes de credenciais

Autenticar aplicativos hospedados no Azure

Credencial	Utilização	Exemplo
DefaultAzureCredential	Fornece uma experiência de autenticação simplificada para começar rapidamente a desenvolver aplicativos executados no Azure.	exemplo
ChainedTokenCredential	Permite que os usuários definam fluxos de autenticação personalizados compondo várias credenciais.	exemplo
EnvironmentCredential	Autentica uma entidade de serviço ou usuário por meio de informações de credenciais especificadas em variáveis de ambiente.	exemplo
ManagedIdentityCredential	Autentica a identidade gerenciada de um recurso do Azure.	exemplo
WorkloadIdentityCredential	Suporta de ID de Carga de Trabalho do Microsoft Entra no Kubernetes.	exemplo

Autenticar entidades de serviço

Credencial	Utilização	Exemplo	Referência
AzurePipelinesCredential	Suporta 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	Utilização	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 de 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 e as permissões do usuário delegado através da cadeia de solicitações		de autenticação em nome
UsernamePasswordCredential	Autentica um usuário com um nome de usuário e senha.	exemplo	de autenticação de nome de utilizador + palavra-passe

Autentique-se através de ferramentas de desenvolvimento

Credencial	Utilização	Exemplo	Referência
AzureCliCredential	Autentique-se 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 habilitado ou a entidade de serviço na CLI do Desenvolvedor do Azure.		de referência da CLI do desenvolvedor do Azure
AzurePowerShellCredential	Autentique-se em um ambiente de desenvolvimento usando o Azure PowerShell.	exemplo	de autenticação do Azure PowerShell
VisualStudioCodeCredential	Autentica como o usuário conectado à extensão de Conta do Azure do Visual Studio Code.		Extensão de Conta do Azure 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.

Principal 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 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 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 do arquivo de certificado, se houver

Nome de utilizador e palavra-passe

Nome da variável	Valor
AZURE_CLIENT_ID	ID de um aplicativo 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 e-mail)
AZURE_PASSWORD	a palavra-passe desse utilizador

A configuração é tentada na ordem acima. Por exemplo, se os valores de um segredo do cliente e de 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 de Avaliação de Acesso Contínuo (CAE) é possível por solicitação. Isso pode ser ativado usando o GetTokenOptions.enableCae(boolean) API. O CAE não é suportado para credenciais de desenvolvedor.

Cache de token

O cache de token é 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 (opt-in).
• Melhorar a resiliência e o desempenho.
• Reduza o número de solicitações feitas ao Microsoft Entra ID para obter tokens de acesso.

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

Autenticação intermediada

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

Solução de problemas

Para obter ajuda com a solução de problemas, consulte o guia de solução de problemas .

Próximos passos

Leia a documentação

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

Suporte à biblioteca do cliente

As bibliotecas de cliente e gerenciamento listadas na página versões do SDK do Azure que oferecem 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 do Azure AD B2C

Esta biblioteca não suporta o serviço Azure AD B2C.

Para outros problemas em aberto, consulte o repositório GitHub da biblioteca.

Fornecer feedback

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

Contribuição

Se você quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.