Biblioteca de cliente da Identidade do Azure para JavaScript – versão 4.2.0
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:
- Código fonte
- Pacote (npm)
- Documentação de Referência da API
- Microsoft Entra ID documentação
- Amostras
Introdução
Migrar da v1 para a v2 de @azure/identity
Se estiver a utilizar a v1 do , veja o guia de @azure/identity
migraçã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.
- 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
- 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.
- Nota: entre as diferentes credenciais exportadas nesta biblioteca,
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
- Uma subscrição do Azure.
- Opcional: a CLI do Azure e/ou Azure PowerShell também podem ser úteis para autenticar num ambiente de desenvolvimento e gerir funções de conta.
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:
- Apresentamos alguns casos de utilização avançados de
@azure/identity
na página Exemplos de Identidade do Azure .- Aqui, temos especificamente uma secção Exemplos Avançados .
- Também temos uma secção que mostra como Autenticar diretamente com o MSAL.
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.
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.
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.
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:
- Ambiente – a
DefaultAzureCredential
irá ler as informações da conta especificadas através de variáveis de ambiente e utilizá-la para autenticar. - 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. - 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. - CLI do Azure – se o programador tiver autenticado uma conta através do comando da CLI
az login
do Azure, aDefaultAzureCredential
será autenticada com essa conta. - Azure PowerShell - Se o programador tiver autenticado com o comando do módulo
Connect-AzAccount
Azure PowerShell, oDefaultAzureCredential
será autenticado com essa conta. - Azure Developer CLI - Se o programador tiver autenticado uma conta através do comando Azure Developer CLI
azd auth login
, oDefaultAzureCredential
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 emaccess_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:
- Serviço de Aplicações do Azure e Funções do Azure
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Máquinas Virtuais do Azure
- Conjuntos de Dimensionamento do Azure Máquinas Virtuais
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 |
Autentique-se num ambiente de desenvolvimento com o principal de serviço ou utilizador 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
podem ser configuradas 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 em 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 de cliente e certificado estiverem ambos presentes, será utilizado o segredo do cliente.
Avaliação de Acesso Contínuo
A partir da versão 3.3.0, é possível aceder a recursos protegidos pela Avaliação de Acesso Contínuo (CAE) por pedido. Isto pode ser ativado com a GetTokenOptions.enableCae(boolean)
API. O CAE não é suportado 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 que as aplicações:
- Colocar tokens em cache na memória (predefinição) e no disco (optar ativamente por participar).
- Melhorar a resiliência e o desempenho.
- Reduza o número de pedidos feitos a Microsoft Entra ID para obter tokens de acesso.
A biblioteca de Identidades do Azure oferece colocação em cache dentro da memória e do disco 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 de gestão listadas na página de versões 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
suporte do Azure AD B2C
Esta biblioteca não suporta a 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.
Azure SDK for JavaScript
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários