Partilhar via

Plug-in do Azure Identity para autenticação intermediada

  • Artigo

Este pacote fornece um plug-in para a biblioteca de Identidade do Azure para JavaScript (@azure/identity) que permite usar um agente de autenticação como WAM.

Um agente de autenticação é um aplicativo executado na máquina de um usuário que gerencia os handshakes de autenticação e a manutenção de token para contas conectadas. Atualmente, apenas o agente de autenticação do Windows, Web Account Manager (WAM), é suportado.

Código fonte | Exemplos | documentação de referência da API | [Documentação do Microsoft Entra ID] (https://learn.microsoft.com/entra/identity/)

Primeiros passos

import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

Pré-requisitos

Instalar o pacote

Este pacote foi projetado para ser usado com o Azure Identity for JavaScript. Instale o @azure/identity e este pacote usando npm:

npm install --save @azure/identity
npm install --save @azure/identity-broker

Ambientes suportados

Os plug-ins do Azure Identity para JavaScript suportam versões estáveis (numeradas pares) do Node.js a partir da v18. Embora os plugins possam ser executados em outras versões Node.js, nenhum suporte é garantido. @azure/identity-broker não suporta ambientes de navegadores.

Conceitos-chave

Se esta for a primeira vez que você usa o @azure/identity ou o Microsoft Entra ID, recomendamos que você leia Usando o @azure/identity com o Microsoft Entra ID primeiro. Este documento lhe dará uma compreensão mais profunda da plataforma e como configurar sua conta do Azure corretamente.

Alças da janela pai

Ao autenticar com o broker via 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 para uma janela específica.

Passagem da conta Microsoft (MSA)

As contas Microsoft (MSA) são contas pessoais criadas pelos utilizadores para aceder aos serviços Microsoft. MSA passthrough é uma configuração herdada que permite aos usuários obter tokens para recursos que normalmente não aceitam logins MSA. Este recurso só está disponível para aplicativos primários. Os usuários que se autenticam com um aplicativo configurado para usar a passagem MSA podem definir legacyEnableMsaPassthrough para true dentro InteractiveBrowserCredentialNodeOptions.brokerOptions para permitir que essas contas pessoais sejam listadas pelo WAM.

Redirecionar URIs

Os aplicativos Microsoft Entra dependem de URIs de redirecionamento para determinar para onde enviar a resposta de autenticação depois que um usuário fizer logon. Para habilitar a autenticação intermediada 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 do Azure Identity

A partir de @azure/identity versão 2.0.0, a biblioteca de cliente Identity para JavaScript inclui uma API de plug-in. Este pacote (@azure/identity-broker) exporta um objeto de plugin que você deve passar como um argumento para a função de useIdentityPlugin de nível superior do pacote @azure/identity. Habilite o broker 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 broker nativo é registrado no pacote @azure/identity e estará disponível no InteractiveBrowserCredential que suporta a 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 para true a 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 uma alça de janela, consulte este exemplo.

Utilizar a conta predefinida para iniciar sessão

Quando a opção useDefaultBrokerAccount estiver definida como true, a credencial tentará usar silenciosamente a conta de corretor padrão. Se o uso da conta padrão falhar, a credencial voltará para a 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), "...");

Solução de problemas

Consulte o Azure Identity [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.

Registo

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 tempo de execução chamando setLogLevel no @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Próximos passos

Fornecer feedback

Se você encontrar bugs ou tiver sugestões, por favor, abrir um problema.

Contribuição

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