Plug-in de Identidade do Azure para autenticação agenciada
Esse pacote fornece um plug-in para a biblioteca de Identidade do Azure para JavaScript (@azure/identity) que permite o uso de um agente de autenticação, como WAM.
Um agente de autenticação é um aplicativo executado no computador de um usuário que gerencia os handshakes de autenticação e a manutenção de token para contas conectadas. Atualmente, há suporte apenas para o agente de autenticação do Windows, o Gerenciador de Contas Web (WAM).
| de código-fonte | documentação de referência da API | [Documentação da ID do Microsoft Entra] (https://video2.skills-academy.com/entra/identity/)
Introdução
import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";
useIdentityPlugin(nativeBrokerPlugin);
Pré-requisitos
- Uma assinatura do Azure.
Instalar o pacote
Esse pacote foi projetado para ser usado com a Identidade do Azure para JavaScript. Instale @azure/identity e este pacote usando npm:
npm install --save @azure/identity
npm install --save @azure/identity-broker
Ambientes com suporte
Os plug-ins de Identidade do Azure para JavaScript dão suporte a versões estáveis (mesmo numeradas) de Node.js a partir da v18. Embora os plug-ins possam ser executados em outras versões Node.js, nenhum suporte é garantido.
@azure/identity-broker
não dá suporte ambientes de navegador.
Principais conceitos
Se esta for sua primeira vez usando @azure/identity ou a ID do Microsoft Entra, recomendamos que você leia Usando @azure/identity com a ID do Microsoft Entra primeiro. Este documento fornecerá uma compreensão mais profunda da plataforma e como configurar sua conta do Azure corretamente.
Identificadores de janela pai
Ao autenticar com o agente por meio de InteractiveBrowserCredential, um identificador de janela pai é necessário para garantir que a caixa de diálogo de autenticação seja mostrada corretamente na janela de solicitação. No contexto de interfaces gráficas do usuário em dispositivos, um identificador de janela é um identificador exclusivo que o sistema operacional atribui a cada janela. Para o sistema operacional Windows, esse identificador é um valor inteiro que serve como referência a uma janela específica.
Passagem da CONTA da Microsoft (MSA)
As MSA (contas da Microsoft) são contas pessoais criadas pelos usuários para acessar os serviços da Microsoft. A passagem msa é uma configuração herdada que permite aos usuários obter tokens para recursos que normalmente não aceitam logons msa. Esse recurso só está disponível para aplicativos de primeira parte. Os usuários que se autenticam com um aplicativo configurado para usar a passagem msa podem definir legacyEnableMsaPassthrough para true dentro de InteractiveBrowserCredentialNodeOptions.brokerOptions para permitir que essas contas pessoais sejam listadas pelo WAM.
URIs de redirecionamento
Os aplicativos do Microsoft Entra dependem de URIs de redirecionamento para determinar para onde enviar a resposta de autenticação após o logon de um usuário. Para habilitar a autenticação agenciada por meio do WAM, um URI de redirecionamento correspondente ao seguinte padrão deve ser registrado no aplicativo:
ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}
Plug-ins de Identidade do Azure
A partir de @azure/identity versão 2.0.0, a biblioteca de clientes de identidade para JavaScript inclui uma API de plug-in. Esse pacote (@azure/identity-broker) exporta um objeto plug-in que você deve passar como um argumento para a função de useIdentityPlugin de nível superior do pacote @azure/identity. Habilite o agente nativo em seu programa da seguinte maneira:
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";
useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
brokerOptions: {
enabled: true,
parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
},
});
Depois de chamar useIdentityPlugin, o plug-in do agente nativo é registrado no pacote de @azure/identity e estará disponível no InteractiveBrowserCredential que dá suporte à autenticação do agente WAM. Essa credencial tem brokerOptions nas opções do construtor.
Exemplos
Depois que o plug-in for registrado, você poderá habilitar a autenticação do agente WAM passando brokerOptions com uma propriedade enabled definida como true para um construtor de credenciais. No exemplo a seguir, usamos o InteractiveBrowserCredential.
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";
useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
brokerOptions: {
enabled: true,
parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
},
});
// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";
// Print out part of the access token
console.log((await credential.getToken(scope)).token.substring(0, 10), "...");
Para obter um exemplo completo de como usar um aplicativo Electron para recuperar um identificador de janela, consulte este exemplo.
Usar a conta padrão para entrar
Quando a opção useDefaultBrokerAccount estiver definida como true, a credencial tentará usar silenciosamente a conta do agente padrão. Se o uso da conta padrão falhar, a credencial retornará à autenticação interativa.
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";
useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
brokerOptions: {
enabled: true,
useDefaultBrokerAccount: true,
parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
},
});
// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";
// Print out part of the access token
console.log((await credential.getToken(scope)).token.substr(0, 10), "...");
Solucionando problemas
Consulte a Identidade do Azure [guia de solução de problemas][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.1.0/sdk/identity/identity/TROUBLESHOOTING.md] para obter detalhes sobre como diagnosticar vários cenários de falha.
Log
Habilitar o registro em log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o registro em log pode ser habilitado em runtime chamando setLogLevel no @azure/logger:
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
Próximas etapas
Fornecer comentários
Se você encontrar bugs ou tiver sugestões, abra um problema.
Contribuindo
Se você quiser contribuir com essa biblioteca, consulte o guia de contribuição para saber mais sobre como criar e testar o código.
impressões 
Azure SDK for JavaScript