Complemento de identidad de Azure para la autenticación asincrónica
Este paquete proporciona un complemento a la biblioteca de identidades de Azure para JavaScript (@azure/identity) que permite usar un agente 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 admite el agente de autenticación de Windows, el Administrador de cuentas web (WAM).
Empezar
import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";
useIdentityPlugin(nativeBrokerPlugin);
Prerrequisitos
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
Los complementos de Identidad de Azure para JavaScript admiten versiones estables (incluso numeradas) de Node.js a partir de la versión 18. 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 esta es la primera vez que usa @azure/identity o id. de Microsoft Entra, le recomendamos que lea Uso de @azure/identity con el identificador de Entra de Microsoft primero. Este documento le proporcionará un conocimiento más profundo de la plataforma y cómo configurar la cuenta de Azure correctamente.
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 identificador es un valor entero que actúa como referencia a una ventana específica.
Acceso directo a la cuenta Microsoft (MSA)
Las cuentas de Microsoft (MSA) son cuentas personales creadas por los usuarios para acceder a los servicios de Microsoft. 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 los URI de redirección para determinar dónde enviar la respuesta de autenticación después de que un 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}
Complementos de identidad de Azure
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.
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 obtener un ejemplo completo del uso de una aplicación Electron para recuperar un identificador de ventana, consulte este ejemplo.
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
Consulte la guía de solución de problemas de Identidad de Azure[guía de solución de problemas][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.1.0/sdk/identity/identity/TROUBLESHOOTING.md] para más información sobre cómo diagnosticar varios escenarios de error.
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 encuentra errores o tiene sugerencias, abra un problema.
Contribuyendo
Si desea contribuir a esta biblioteca, consulte la guía de contribución de para obtener más información sobre cómo compilar y probar el código.
Azure SDK for JavaScript