Plugin Azure Identity para autenticação intermediária

Este pacote fornece um plugin para a biblioteca Azure Identity para JavaScript (@azure/identity) que permite a utilização de um broker 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 corretor de Windows authentication, Web Account Manager (WAM), é suportado.

Código-fonte | Samples | API documentação de referência | Microsoft Entra ID documentação

Primeiros passos

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

useIdentityPlugin(nativeBrokerPlugin);

Pré-requisitos

• Uma subscrição Azure.

Nota: Para o desenvolvimento local com @azure/identity-brokero , pode ser necessário instalar ferramentas adicionais. node-gyp é usado para compilar addons para acessar APIs do sistema. Os requisitos de instalação estão listados no README node-gyp.

No Linux, a biblioteca usa libsecret , então você pode precisar instalá-la. Dependendo da sua distribuição, você precisará executar o seguinte comando:

• Debian/Ubuntu: sudo apt-get install libsecret-1-dev
• Baseado em Red Hat: sudo yum install libsecret-devel
• Arch Linux: sudo pacman -S libsecret

Instalar o pacote

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

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

Ambientes suportados

Azure Plugins Identity para JavaScript suportam versões estáveis (com número par) do Node.js a partir da v20. 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 for a sua primeira vez a usar @azure/identity ou Microsoft Entra ID, recomendamos que leia primeiro Usando @azure/identity com Microsoft Entra ID. Este documento dar-lhe-á uma compreensão mais profunda da plataforma e de como configurar corretamente a sua conta Azure.

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 operativo Windows, este handle é um valor inteiro que serve de referência a uma janela específica.

Passthrough 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

As aplicações Microsoft Entra dependem de URIs de redirecionamento para determinar para onde enviar a resposta de autenticação após o utilizador iniciar sessão. 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}

Azure Identity plugins

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.

Notas: A partir de @azure/identity versão 4.11.0-beta.1, DefaultAzureCredential fornece suporte para iniciar sessão através do Gestor de Contas Web Windows. Habilite o broker nativo em seu programa da seguinte maneira:

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

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

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 um exemplo completo de utilização de uma aplicação Electron para recuperar uma maçaneta de janela, veja esta amostra.

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 guia Azure Identity resolução de problemas para 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 encontrares bugs ou tiveres sugestões, por favor abre uma questão.

Contribuição

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