Plugin Azure Identity para autenticación intermediada

Este paquete proporciona un complemento para la biblioteca Azure Identity para JavaScript (@azure/identity) que permite el uso de un broker de autenticación como WAM.

Un agente de autenticación es una aplicación que se ejecuta en la máquina de un usuario que administra los protocolos de enlace de autenticación y el mantenimiento de tokens para las cuentas conectadas. Actualmente, solo se soporta el broker de autenticación de Windows, Web Account Manager (WAM).

Código fuente | Samples | API documentación de referencia | Microsoft Entra ID documentación

Empezar

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

useIdentityPlugin(nativeBrokerPlugin);

Prerrequisitos

• Una suscripción Azure.

Nota: Para el desarrollo local con @azure/identity-broker, es posible que deba instalar herramientas adicionales. node-gyp se utiliza para compilar complementos para acceder a las API del sistema. Los requisitos de instalación se enumeran en el archivo README node-gyp.

En Linux, la biblioteca se usa libsecret , por lo que es posible que deba instalarla. Dependiendo de su distribución, deberá ejecutar el siguiente comando:

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

Instalación del paquete

Este paquete está diseñado para usarse con Azure Identity para JavaScript. Instale tanto @azure/identity como este paquete mediante npm:

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

Entornos admitidos

Azure Los plugins de identidad para JavaScript soportan versiones estables (con número par) de Node.js a partir de la v20. Aunque los complementos se pueden ejecutar en otras versiones de Node.js, no se garantiza ninguna compatibilidad. @azure/identity-broker no admite entornos de explorador.

Conceptos clave

Si es la primera vez que usas @azure/identity o Microsoft Entra ID, te recomendamos que leas primero Usando @azure/identity con Microsoft Entra ID. Este documento te dará una comprensión más profunda de la plataforma y de cómo configurar correctamente tu cuenta de Azure.

Identificadores de ventana principal

Al autenticarse con el agente a través de InteractiveBrowserCredential, se requiere un identificador de ventana principal para asegurarse de que el cuadro de diálogo de autenticación se muestra correctamente en la ventana de solicitud. En el contexto de las interfaces gráficas de usuario en los dispositivos, un identificador de ventana es un identificador único que el sistema operativo asigna a cada ventana. Para el sistema operativo Windows, este handle es un valor entero que sirve como referencia a una ventana específica.

Paso de la cuenta cuenta Microsoft (MSA)

Las cuentas de Microsoft (MSA) son cuentas personales creadas por los usuarios para acceder a los servicios de Microsoft Services. El paso a través de MSA es una configuración heredada que permite a los usuarios obtener tokens a recursos que normalmente no aceptan inicios de sesión de MSA. Esta característica solo está disponible para aplicaciones propias. Los usuarios que se autentican con una aplicación configurada para usar el acceso directo de MSA pueden establecer legacyEnableMsaPassthrough en true dentro de InteractiveBrowserCredentialNodeOptions.brokerOptions para permitir que WAM muestre estas cuentas personales.

URI de redirección

Las aplicaciones de Microsoft Entra dependen de URI de redirección para determinar dónde enviar la respuesta de autenticación después de que el usuario haya iniciado sesión. Para habilitar la autenticación asincrónica a través de WAM, se debe registrar un URI de redirección que coincida con el siguiente patrón en la aplicación:

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Azure Identity plugins

A partir de @azure/identity versión 2.0.0, la biblioteca cliente de identidad para JavaScript incluye una API de complemento. Este paquete (@azure/identity-broker) exporta un objeto de complemento que debe pasar como argumento a la función de useIdentityPlugin de nivel superior del paquete de @azure/identity. Habilite el agente nativo en el programa de la siguiente manera:

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
  },
});

Después de llamar a useIdentityPlugin, el complemento de agente nativo se registra en el paquete de @azure/identity y estará disponible en el InteractiveBrowserCredential que admite la autenticación del agente WAM. Esta credencial tiene brokerOptions en las opciones del constructor.

Notas: A partir de @azure/identity versión 4.11.0-beta.1, DefaultAzureCredential ofrece soporte para iniciar sesión a través del Gestor de Cuentas Web Windows. Habilite el agente nativo en el programa de la siguiente manera:

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

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

Ejemplos

Una vez registrado el complemento, puede habilitar la autenticación del agente WAM pasando brokerOptions con una propiedad enabled establecida en true a un constructor de credenciales. En el ejemplo siguiente, usamos el 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 un ejemplo completo de cómo usar una app Electron para recuperar un mango de ventana, véase esta muestra.

Uso de la cuenta predeterminada para el inicio de sesión

Cuando la opción useDefaultBrokerAccount se establece en true, la credencial intentará usar silenciosamente la cuenta de agente predeterminada. Si se produce un error en el uso de la cuenta predeterminada, la credencial volverá a la autenticación interactiva.

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), "...");

Solución de problemas

Consulta la guía de resolución de problemas Azure> Identity < para detalles sobre cómo diagnosticar diversos escenarios de fallo.

Registro

Habilitar el registro puede ayudar a descubrir información útil sobre errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en el @azure/logger:

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

setLogLevel("info");

Pasos siguientes

Proporcionar comentarios

Si encuentras bugs o tienes sugerencias, por favor abre un problema.

Contribuyendo

Si quieres contribuir a esta biblioteca, consulta la guía contribución para aprender más sobre cómo construir y probar el código.