Usando o MSAL Node com o Broker do macOS

Biblioteca do Microsoft Authenticator (MSAL) Node pode usar o agente de autenticação macOS para fornecer SSO (logon único) e aquisição de token seguro usando contas conhecidas pelo sistema operacional. Este artigo explica o broker do macOS e como habilitar e usar a autenticação mediada por broker no MSAL Node.

Para obter uma visão geral do suporte do broker em todas as plataformas, consulte Usando o MSAL Node com o Broker de Token Nativo.

O que é o broker do macOS

No macOS, o agente de autenticação é fornecido pelo plug-in Microsoft Enterprise SSO para dispositivos Apple, que é fornecido com o aplicativo Portal da Empresa. O agente gerencia os handshakes de autenticação e o ciclo de vida dos tokens para contas conectadas. Os principais benefícios incluem:

• Segurança aprimorada. Melhorias de segurança são fornecidas por meio de atualizações do broker, sem exigir alterações no código do aplicativo. Os tokens de atualização são associados ao dispositivo e protegidos contra exfiltração.
• Integração do sistema. Os usuários podem reutilizar contas de entrada existentes de Portal da Empresa, reduzindo a reentrada de credenciais.
• Proteção de token. O intermediário garante que os tokens de atualização sejam vinculados ao contexto do dispositivo.

Plataformas e arquiteturas com suporte

Pré-requisitos

• Node.js 18 ou posterior
• Instalar @azure/msal-node-extensions como uma dependência
• O dispositivo deve ser registrado por meio de Portal da Empresa. Após o registro, verifique se outros aplicativos Microsoft podem entrar por meio da extensão SSO (por exemplo, você pode entrar no Word por meio de Portal da Empresa).
• Registre o URI de redirecionamento do broker no registro do seu aplicativo. Para obter os valores de URI com suporte, consulte URI de redirecionamento.

URI de redirecionamento

Para fluxos de agente do macOS, você deve registrar um URI de redirecionamento específico da plataforma na plataforma Aplicativos móveis e de área de trabalho no portal do Azure.

Para aplicativos não assinados (scripts, ferramentas da CLI):

Use o seguinte URI de redirecionamento para aplicativos não assinados, como scripts e ferramentas da CLI:

msauth.com.msauth.unsignedapp://auth

Para aplicativos assinados/empacotados:

Use o seguinte formato de URI de redirecionamento para aplicativos assinados ou empacotados:

msauth.<your-bundle-id>://auth

Substitua <your-bundle-id> pelo identificador de pacote da Apple do aplicativo (por exemplo, msauth.com.example.myapp://auth).

habilitar o recurso

Habilitar o agente macOS requer a mesma configuração que Windows. Passe uma instância de NativeBrokerPlugin na configuração do broker:

import { PublicClientApplication, Configuration } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id",
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin(),
    },
};

const pca = new PublicClientApplication(msalConfig);

Aquisição de tokens

Aquisição interativa de token

Use acquireTokenInteractive para solicitar um token por meio do agente macOS:

const tokenRequest = {
    scopes: ["User.Read"],
};

const result = await pca.acquireTokenInteractive(tokenRequest);
console.log("Access token:", result.accessToken);

Aquisição silenciosa de token

Após uma entrada interativa inicial, as solicitações de token subsequentes podem ser feitas silenciosamente:

const accounts = await pca.getAllAccounts();

if (accounts.length > 0) {
    const silentRequest = {
        scopes: ["User.Read"],
        account: accounts[0],
    };

    const result = await pca.acquireTokenSilent(silentRequest);
    console.log("Access token (silent):", result.accessToken);
}

Armazenamento de token em cache

O intermediário de autenticação gerencia o cache dos tokens de atualização e de acesso. Os tokens adquiridos por meio do agente são gerenciados pelo próprio agente e são associados ao dispositivo. Você não precisa configurar o cache personalizado ao usar o broker.

Diferenças ao usar o agente macOS

• Quando o broker precisa solicitar uma interação, uma caixa de diálogo nativa de autenticação do macOS é exibida. Isso altera a experiência do usuário (UX) em comparação com a autenticação baseada em navegador.
• O parâmetro forceRefresh para acquireTokenSilent não tem suporte. Você pode receber um token armazenado em cache do broker, independentemente dessa sinalização.
• Há suporte para prova de posse (PoP) do token de acesso por meio do agente.

Limitations

• As autoridades do Azure AD B2C e do Serviços de Federação do Active Directory (AD FS) não têm suporte por meio do agente do macOS.
• Não há suporte para IDPs (provedores de identidade de terceiros).
• Portal da Empresa deve ser instalado e o dispositivo deve ser registrado para que o agente funcione.
• msal-node não retornará a um navegador se o agente não estiver disponível. Habilite o broker apenas em ambientes que o suportem.