Biblioteca de cliente da Identidade do Azure para JavaScript – versão 4.1.0

  • Artigo

A biblioteca de Identidades do Azure fornece autenticação de tokens Microsoft Entra ID (anteriormente Azure Active Directory) através de um conjunto de implementações tokenCredential convenientes.

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

Ligações principais:

Introdução

Migrar da v1 para a v2 de @azure/identity

Se estiver a utilizar a v1 do , veja o guia de @azure/identitymigração para atualizar para v2.

Ambientes atualmente suportados

  • Versões LTS do Node.js
    • Nota: Se a sua aplicação for executada no Node.js v8 ou inferior e não conseguir atualizar a versão Node.js para a versão estável mais recente, afixe @azure/identity a dependência à versão 1.1.0.
  • Versões mais recentes do Safari, Chrome, Edge e Firefox.
    • Nota: entre as diferentes credenciais exportadas nesta biblioteca, InteractiveBrowserCredential está a única que é suportada no browser.

Veja a nossa política de suporte para obter mais detalhes.

Instalar o pacote

Instalar a Identidade do Azure com npm:

npm install --save @azure/identity

Pré-requisitos

Quando utilizar @azure/identity

As classes de credenciais expostas por @azure/identity estão focadas em fornecer a forma mais simples de autenticar os clientes do SDK do Azure localmente, nos seus ambientes de desenvolvimento e em produção. Visamos 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 a expandir-nos ativamente para abranger mais cenários. Para obter uma lista completa das credenciais oferecidas, veja a secção Classes de Credenciais .

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

A maioria dos tipos de credenciais oferecidos através @azure/identity da Utilização da Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js). Especificamente, utilizamos as bibliotecas de MSAL.js v2, que utilizam o Fluxo de Código de Autorização 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 concebidas para fornecer suporte robusto para os protocolos de autenticação suportados pelo Azure.

Quando utilizar outra coisa

Os @azure/identity tipos de credenciais 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. Isto significa que os programadores podem escrever os seus próprios tipos de credenciais para suportar casos de autenticação não abrangidos pelo @azure/identity. Para saber mais, veja Credenciais Personalizadas.

Embora os nossos tipos de credenciais suportem muitos casos avançados, os programadores podem querer o controlo total do protocolo de autenticação. Para esse caso de utilização, recomendamos que utilize diretamente a Biblioteca de Autenticação da Microsoft para JavaScript (MSAL.js ). Pode ler mais através das seguintes ligações:

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

Autenticar o cliente no ambiente de desenvolvimento

Embora recomendemos a utilização da autenticação de identidade gerida ou do principal de serviço na sua aplicação de produção, é normal que um programador utilize a sua própria conta para autenticar chamadas para serviços do Azure ao depurar e executar código localmente. Existem várias ferramentas de programador que podem ser utilizadas para efetuar esta autenticação no seu ambiente de desenvolvimento.

Autenticar através do Azure Developer CLI

Os programadores que codificam fora de um IDE também podem utilizar o [Azure Developer CLI][azure_developer_cli] para autenticar. As aplicações que utilizam o DefaultAzureCredential ou o AzureDeveloperCliCredential podem utilizar esta conta para autenticar chamadas na respetiva aplicação quando são executadas localmente.

Para autenticar com o [Azure Developer CLI][azure_developer_cli], os utilizadores podem executar o comando azd auth login. Para os utilizadores em execução num sistema com um browser predefinido, o Azure Developer CLI iniciará o browser para autenticar o utilizador.

Para sistemas sem um browser predefinido, o azd auth login --use-device-code comando utilizará o fluxo de autenticação de código do dispositivo.

Autenticar através da CLI do Azure

As aplicações que utilizam o AzureCliCredential, diretamente ou através do DefaultAzureCredential, podem utilizar a conta da CLI do Azure para autenticar chamadas na aplicação quando são executadas localmente.

Para autenticar com a CLI do Azure , os utilizadores podem executar o comando az login. Para os utilizadores em execução num sistema com um browser predefinido, a CLI do Azure iniciará o browser para autenticar o utilizador.

Início de Sessão da Conta da CLI do Azure

Para sistemas sem um browser predefinido, o az login comando utilizará o fluxo de autenticação de código do dispositivo. O utilizador também pode forçar a CLI do Azure a utilizar o fluxo de código do dispositivo em vez de iniciar um browser ao especificar o --use-device-code argumento.

Início de Sessão do Código do Dispositivo da Conta da CLI do Azure

Autenticar através de Azure PowerShell

As aplicações que utilizam o AzurePowerShellCredential, diretamente ou através do DefaultAzureCredential, podem utilizar a conta ligada ao Azure PowerShell para autenticar chamadas na aplicação quando são executadas localmente.

Para autenticar com Azure PowerShell os utilizadores podem executar o Connect-AzAccount cmdlet. Por predefinição, a CLI Connect-AzAccount do Azure iniciará o browser predefinido para autenticar uma conta de utilizador.

Azure PowerShell Início de Sessão na Conta

Se não for possível suportar a autenticação interativa na sessão, o -UseDeviceAuthentication argumento forçará o cmdlet a utilizar um fluxo de autenticação de código do dispositivo, semelhante à opção correspondente na credencial da CLI do Azure.

Autenticar através do Visual Studio Code

Os programadores que utilizam o Visual Studio Code podem utilizar a extensão da Conta do Azure para se autenticarem através do editor. As aplicações que utilizam VisualStudioCodeCredential podem utilizar esta conta para autenticar chamadas na respetiva aplicação quando são executadas localmente.

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

Além disso, utilize o @azure/identity-vscode pacote de plug-in. Este pacote fornece as dependências de VisualStudioCodeCredential e permite-lhe. Veja Plug-ins.

É um problema conhecido que VisualStudioCodeCredential não funciona com as versões da extensão da Conta do Azure mais recentes do que a 0.9.11. Está em curso uma correção a longo prazo deste problema. Entretanto, considere autenticar através da CLI do Azure.

Autenticar o cliente nos browsers

Para autenticar clientes do SDK do Azure em browsers, oferecemos o InteractiveBrowserCredential, que pode ser definido para utilizar redirecionamento ou pop-ups para concluir o fluxo de autenticação. É necessário criar primeiro um Registo de Aplicação Azure AD no portal do Azure da sua aplicação Web.

Conceitos-chave

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

Credencial

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

A biblioteca de Identidades do Azure centra-se na autenticação OAuth com Microsoft Entra ID e oferece uma variedade de classes de credenciais capazes de adquirir um token de Microsoft Entra para autenticar pedidos de serviço. Todas as classes de credenciais nesta biblioteca são implementações da classe abstrata TokenCredential e qualquer uma delas pode ser utilizada para construir clientes de serviço capazes de autenticar com um TokenCredential.

Veja Classes de Credenciais.

DefaultAzureCredential

O DefaultAzureCredential é adequado para a maioria dos cenários em que a aplicação se destina a ser executada no Azure. Isto deve-se ao facto de combinar DefaultAzureCredential credenciais normalmente utilizadas para autenticar quando implementadas com credenciais utilizadas para autenticar num ambiente de desenvolvimento.

Nota: DefaultAzureCredential destina-se a simplificar a introdução ao SDK ao processar cenários comuns com comportamentos predefinidos razoáveis. Os programadores que pretendam ter mais controlo ou cujo cenário não seja servido pelas predefinições devem utilizar outros tipos de credenciais.

Se for utilizado a partir de Node.js, o DefaultAzureCredential tentará autenticar-se através dos seguintes mecanismos por ordem:

Fluxo de autenticação DefaultAzureCredential

  1. Ambiente – a DefaultAzureCredential irá ler as informações da conta especificadas através de variáveis de ambiente e utilizá-la para autenticar.
  2. Identidade da Carga de Trabalho – se a aplicação for implementada para Azure Kubernetes Service com a Identidade Gerida ativada, DefaultAzureCredential será autenticada com a mesma.
  3. Identidade Gerida – se a aplicação for implementada num anfitrião do Azure com a Identidade Gerida ativada, a DefaultAzureCredential será autenticada com essa conta.
  4. CLI do Azure – se o programador tiver autenticado uma conta através do comando da CLI az login do Azure, a DefaultAzureCredential será autenticada com essa conta.
  5. Azure PowerShell - Se o programador tiver autenticado com o comando do módulo Connect-AzAccount Azure PowerShell, o DefaultAzureCredential será autenticado com essa conta.
  6. Azure Developer CLI - Se o programador tiver autenticado uma conta através do comando Azure Developer CLIazd auth login, o DefaultAzureCredential será autenticado com essa conta.

Política de continuação

A partir da versão 3.3.0, DefaultAzureCredential tentará autenticar-se com todas as credenciais de programador até que uma seja bem-sucedida, independentemente de quaisquer erros que tenham ocorrido nas credenciais anteriores do programador. Por exemplo, uma credencial de programador pode tentar obter um token e falhar, pelo DefaultAzureCredential que continuará para a credencial seguinte no fluxo. As credenciais de serviço implementadas irão parar o fluxo com uma exceção emitida se forem capazes de tentar obter tokens, mas não receberem uma.

Isto permite experimentar todas as credenciais de programador no seu computador, ao mesmo tempo que tem um comportamento previsível implementado.

Nota sobre VisualStudioCodeCredential

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

Plug-ins

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

  • @azure/identity-broker, que fornece suporte de autenticação mediada através de um mediador nativo, como o Gestor de Conta Web.
  • @azure/identity-cache-persistence, que fornece colocação em cache de tokens persistente no Node.js através de um sistema de armazenamento seguro nativo fornecido pelo seu sistema operativo. Este plug-in permite que os valores em access_token cache persistam entre sessões, o que significa que um fluxo de início de sessão interativo não precisa de ser repetido desde que esteja disponível um token em cache.

Exemplos

Pode encontrar mais exemplos de utilização de várias credenciais na Página de Exemplos de Identidade do Azure

Autenticar com o DefaultAzureCredential

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

Especifique uma identidade gerida atribuída pelo utilizador com o DefaultAzureCredential

Um cenário relativamente comum envolve a autenticação através de uma identidade gerida atribuída pelo utilizador para um recurso do Azure. Explore o exemplo de Autenticação de uma identidade gerida atribuída pelo utilizador com DefaultAzureCredential para ver como esta tarefa é efetuada numa tarefa relativamente simples que pode ser configurada com variáveis de ambiente ou código.

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

Embora a DefaultAzureCredential seja geralmente a forma mais rápida de começar a desenvolver aplicações para o Azure, os utilizadores mais avançados poderão querer personalizar as credenciais consideradas ao autenticar. Permite ChainedTokenCredential que os utilizadores combinem várias instâncias de credenciais para definir uma cadeia personalizada de credenciais. Este exemplo demonstra a criação de uma ChainedTokenCredential que tentará autenticar com duas instâncias configuradas de forma diferente de ClientSecretCredential, para autenticar a KeyClient das chaves @azure/keyvault:

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 gerida

A autenticação de identidade gerida é suportada através das DefaultAzureCredential classes de credenciais ou ManagedIdentityCredential diretamente para os seguintes serviços do Azure:

Para obter exemplos de como utilizar a identidade gerida para autenticação, veja os exemplos.

Configuração da nuvem

Credenciais predefinidas para autenticar no ponto final Microsoft Entra para a Cloud Pública do Azure. Para aceder a recursos noutras clouds, como Azure Government ou numa nuvem privada, configure as credenciais com o authorityHost argumento no construtor. A AzureAuthorityHosts interface define as autoridades para clouds conhecidas. Para a cloud do Governo dos E.U.A., pode instanciar uma credencial desta 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 necessitam desta configuração. As credenciais que se autenticam através de uma ferramenta de desenvolvimento, como AzureCliCredential, utilizam a configuração dessa ferramenta. Da mesma forma, aceita um authorityHost argumento, VisualStudioCodeCredential mas é predefinido para a authorityHost definição Azure: Cloud do Visual Studio Code correspondente.

Classes de credenciais

Autenticar aplicações alojadas no Azure

Credencial Utilização Exemplo
DefaultAzureCredential Fornece uma experiência de autenticação simplificada para começar rapidamente a desenvolver aplicações executadas no Azure. exemplo
ChainedTokenCredential Permite que os utilizadores definam fluxos de autenticação personalizados compondo múltiplas credenciais. exemplo
EnvironmentCredential Autentica um principal de serviço ou utilizador através de informações de credenciais especificadas em variáveis de ambiente. exemplo
ManagedIdentityCredential Autentica a identidade gerida de um recurso do Azure. exemplo
WorkloadIdentityCredential Suporta ID de carga de trabalho Microsoft Entra no Kubernetes. exemplo

Autenticar principais de serviço

Credencial Utilização Exemplo Referência
ClientAssertionCredential Autentica um principal de serviço com uma asserção de cliente assinada. exemplo Autenticação do principal de serviço
ClientCertificateCredential Autentica um principal de serviço com um certificado. exemplo Autenticação do principal de serviço
ClientSecretCredential Autentica um principal de serviço com um segredo. exemplo Autenticação do principal de serviço

Autenticar utilizadores

Credencial Utilização Exemplo Referência
AuthorizationCodeCredential Autentica um utilizador com um código de autorização obtido anteriormente. exemplo Código de autenticação OAuth2
DeviceCodeCredential Autentica interativamente um utilizador em dispositivos com IU limitada. exemplo Autenticação do código do dispositivo
InteractiveBrowserCredential Autentica interativamente um utilizador com o browser de sistema predefinido. Leia mais sobre como isto acontece aqui. exemplo Código de autenticação OAuth2
OnBehalfOfCredential Propaga a identidade e as permissões de utilizador delegados através da cadeia de pedidos Autenticação em nome de
UsernamePasswordCredential Autentica um utilizador com um nome de utilizador e palavra-passe. exemplo Nome de utilizador + autenticação por palavra-passe

Autenticar através de ferramentas de desenvolvimento

Credencial Utilização Exemplo Referência
AzureCliCredential Autenticar num ambiente de desenvolvimento com a CLI do Azure. exemplo Autenticação da CLI do Azure
AzureDeveloperCliCredential Autenticar num ambiente de desenvolvimento com o utilizador ou principal de serviço ativado no Azure Developer CLI. Referência Azure Developer CLI
AzurePowerShellCredential Autenticar num ambiente de desenvolvimento com Azure PowerShell. exemplo autenticação Azure PowerShell
VisualStudioCodeCredential Autentica-se como o utilizador que iniciou sessão na extensão da Conta do Azure do Visual Studio Code. Extensão da Conta do Azure do VS Code

Variáveis de ambiente

DefaultAzureCredential e EnvironmentCredential pode ser configurado 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 uma aplicação Microsoft Entra
AZURE_TENANT_ID ID do inquilino Microsoft Entra da aplicação
AZURE_CLIENT_SECRET um dos segredos do cliente da aplicação

Principal de serviço com certificado

Nome da variável Valor
AZURE_CLIENT_ID ID de uma aplicação Microsoft Entra
AZURE_TENANT_ID ID do inquilino Microsoft Entra da aplicação
AZURE_CLIENT_CERTIFICATE_PATH caminho para um ficheiro de certificado codificado por PEM, incluindo chave privada
AZURE_CLIENT_CERTIFICATE_PASSWORD palavra-passe do ficheiro de certificado, se existir

Nome de utilizador e palavra-passe

Nome da variável Valor
AZURE_CLIENT_ID ID de uma aplicação Microsoft Entra
AZURE_TENANT_ID ID do inquilino Microsoft Entra da aplicação
AZURE_USERNAME um nome de utilizador (normalmente um endereço de e-mail)
AZURE_PASSWORD palavra-passe desse utilizador

A configuração é tentada pela ordem acima. Por exemplo, se os valores de um segredo e certificado de cliente estiverem presentes, o segredo do cliente será utilizado.

Avaliação de Acesso Contínuo

A partir da versão 3.3.0, o acesso aos recursos protegidos pela Avaliação de Acesso Contínuo (CAE) é possível por pedido. Isto pode ser ativado com a GetTokenOptions.enableCae(boolean) API. A CAE não é suportada para credenciais de programador.

Colocação em cache de tokens

A colocação em cache de tokens é uma funcionalidade fornecida pela biblioteca de Identidade do Azure que permite às aplicações:

  • Colocar tokens em cache na memória (predefinição) e no disco (opt-in).
  • Melhorar a resiliência e o desempenho.
  • Reduza o número de pedidos feitos ao Microsoft Entra ID para obter tokens de acesso.

A biblioteca de Identidades do Azure oferece colocação em cache no disco dentro da memória e persistente. Para obter mais detalhes, veja a documentação de colocação em cache de tokens.

Autenticação mediada

Um mediador de autenticação é uma aplicação que é executada no computador de um utilizador e gere os handshakes de autenticação e a manutenção de tokens para contas ligadas. Atualmente, apenas o Gestor de Conta Web (WAM) do Windows é suportado. Para ativar o suporte, utilize o @azure/identity-broker pacote. Para obter detalhes sobre a autenticação com o WAM, veja a documentação do plug-in do mediador.

Resolução de problemas

Para obter ajuda com a resolução de problemas, veja o guia de resolução de problemas.

Passos seguintes

Ler a documentação

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

Suporte da biblioteca de cliente

As bibliotecas de cliente e gestão listadas na página de lançamentos do SDK do Azure que suportam Microsoft Entra autenticação aceitam credenciais desta biblioteca. Saiba mais sobre como utilizar estas bibliotecas na respetiva documentação, que está ligada a partir da página de lançamentos.

Problemas conhecidos

Azure AD suporte B2C

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

Para outros problemas abertos, veja o repositório do GitHub da biblioteca.

Enviar comentários

Se encontrar erros ou tiver sugestões, abra um problema.

Contribuir

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

Impressões