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 o 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 WAM (Gerenciador de Contas Web).
Código-fonte | Amostras | Documentação de referência da API | [Documentação da ID do Microsoft Entra] (https://video2.skills-academy.com/entra/identity/)
Introdução
import { nativeBrokerPlugin } from "@azure/identity-broker";
import { useIdentityPlugin } from "@azure/identity";
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 esse @azure/identity pacote usando npm:
npm install --save @azure/identity
npm install --save @azure/identity-broker
Ambientes compatíveis
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 a ambientes de navegador.
Principais conceitos
Se esta for sua primeira vez usando @azure/identity ou a ID do Microsoft Entra, recomendamos que você leia Usar @azure/identity com a ID do Microsoft Entra primeiro. Esse documento fornecerá uma compreensão mais profunda da plataforma e de como configurar a conta do Azure corretamente.
Identificadores da janela pai
Ao autenticar com o agente por meio InteractiveBrowserCredentialde , 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 uma referência a uma janela específica.
Passagem da conta 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 que os usuários obtenham 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 como true dentro 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 da @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 nível useIdentityPlugin superior do @azure/identity pacote. Habilite o agente nativo em seu programa da seguinte maneira:
import { nativeBrokerPlugin } from "@azure/identity-broker";
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
brokerOptions: {
enabled: true,
},
});
Depois de chamar useIdentityPlugin, o plug-in do agente nativo é registrado no @azure/identity pacote e estará disponível no que dá suporte à autenticação do InteractiveBrowserCredential 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 enabled propriedade definida como true para um construtor de credenciais. No exemplo a seguir, usamos o InteractiveBrowserCredential.
import { nativeBrokerPlugin } from "@azure/identity-broker";
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
useIdentityPlugin(nativeBrokerPlugin);
async function main() {
const credential = new InteractiveBrowserCredential({
brokerOptions: {
enabled: true,
parentWindowHandle: <insert_current_window_handle>
},
});
// 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), "...");
}
main().catch((error) => {
console.error("An error occurred:", error);
process.exit(1);
});
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 for 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 { nativeBrokerPlugin } from "@azure/identity-broker";
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
useIdentityPlugin(nativeBrokerPlugin);
async function main() {
const credential = new InteractiveBrowserCredential({
brokerOptions: {
enabled: true,
useDefaultBrokerAccount: true,
parentWindowHandle: <insert_current_window_handle>
},
});
// 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), "...");
}
main().catch((error) => {
console.error("An error occurred:", error);
process.exit(1);
});
Solução de 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.0.1/sdk/identity/identity/TROUBLESHOOTING.md] para obter detalhes sobre como diagnosticar vários cenários de falha.
Registro em log
A habilitação do 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 log pode ser habilitado no runtime chamando setLogLevel em @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.
Contribuição
Se você quiser contribuir com essa biblioteca, confira o guia de contribuição para saber mais sobre como criar e testar o código.
Azure SDK for JavaScript