Biblioteca de cliente 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 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
• Microsoft Entra Documentação de identificação
• Amostras

Primeiros passos

Ambientes atualmente suportados

• Versões LTS do Node.js
• Versões mais recentes do Safari, Chrome, Edge e Firefox.
  • Nota: Entre as diferentes credenciais exportadas nesta biblioteca, InteractiveBrowserCredential é a única suportada no navegador.

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

Instalar o pacote

Instale o Azure Identity com npm:

npm install --save @azure/identity

Pré-requisitos

• Uma subscrição 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> funciona 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 cenários avançados, os desenvolvedores podem querer usar Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js diretamente. Considere o uso do MSAL.js nos seguintes cenários:

• Desenvolvedores que desejam controle total do protocolo de autenticação e sua configuração.
• Nossos tipos de credenciais são 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 do MSAL.js para ter mais controle sobre o fluxo de autenticação e o cache de tokens.

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. 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 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 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 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 o da 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.

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 usa 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 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.

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ça o cmdlet a usar um fluxo de autenticação de código de 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 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 várias 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

DefaultAzureCredential simplifica a autenticação ao desenvolver aplicativos que implantam 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 de desenvolvedor anteriores tenham experimentado. Por exemplo, uma credencial de desenvolvedor pode tentar obter um token e falhar, para que DefaultAzureCredential continue para a próxima credencial no fluxo. As credenciais de serviço implantadas interrompem 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 DefaultAzureCredential

Este exemplo demonstra a autenticação do KeyClient da biblioteca de cliente @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);

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

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 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 ChainedTokenCredential que tenta autenticar usando duas instâncias configuradas de forma diferente do ClientSecretCredentiale, em seguida, autenticar o KeyClient a partir 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 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
• Azure Kubernetes Service
• 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. O enum AzureAuthorityHosts define autoridades para nuvens bem conhecidas. Para a nuvem do governo dos EUA, você pode instanciar 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 sua nuvem. Essa abordagem é útil ao configurar várias credenciais para autenticação na mesma nuvem ou quando o ambiente implantado precisa definir a nuvem de destino:

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

O enum AzureAuthorityHosts define autoridades para nuvens bem conhecidas para sua conveniência; no entanto, se a autoridade da sua nuvem não estiver listada no 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 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

Cadeias de credenciais

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

Autenticar aplicativos hospedados no Azure

Credencial	Utilização	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	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	(opcional) senha do arquivo de certificado, se houver
AZURE_CLIENT_SEND_CERTIFICATE_CHAIN	(opcional) Enviar cadeia de certificados no cabeçalho x5c para suportar o nome do assunto / autenticação baseada no emissor

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 anterior. 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 informações, 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, abrir um problema.

Contribuição

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