extensiones de autenticación de Microsoft para Node

Las extensiones de autenticación de Microsoft para Node ofrecen mecanismos seguros para que las aplicaciones cliente realicen la serialización y la persistencia de la caché de tokens multiplataforma.

MsAL Node requiere que los desarrolladores implementen su propia lógica para conservar la caché de tokens. Las extensiones de nodo MSAL tienen como objetivo proporcionar una implementación sólida, segura y configurable de la peristencia de caché de tokens en Windows, Mac y Linux para aplicaciones cliente públicas (clientes de escritorio, aplicaciones de la CLI, etc.). Proporciona mecanismos para cifrar y acceder a la caché de tokens mediante varios procesos simultáneamente.

Las plataformas compatibles son Windows, Mac y Linux:

Windows: DPAPI se usa para el cifrado.
MAC: la cadena de claves MAC se usa a través de npm keytar.
Linux: LibSecret se usa para almacenar en "Servicio secreto" a través de npm keytar.

Code

Creación de la capa de persistencia

La API para crear la capa de persistencia variará en función de la plataforma de destino.

Como alternativa, puede usar la createPersistence API de PersistenceCreator , ya que es un contenedor genérico y selecciona el método de persistencia adecuado basado en la plataforma o sistema operativo.

const { PublicClientApplication } = require("@azure/msal-node");
const {
  DataProtectionScope,
  PersistenceCreator,
  PersistenceCachePlugin,
} = require("@azure/msal-node-extensions");

const persistence = await PersistenceCreator.createPersistence({
                cachePath: "path/to/cache/file.json",
                dataProtectionScope: DataProtectionScope.CurrentUser,
                serviceName: "test-msal-electron-service",
                accountName: "test-msal-electron-account",
                usePlaintextFileOnLinux: false,
          });
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(persistence);
                    },
                });

Como alternativa, puede usar las siguientes opciones específicas de la plataforma:


const { FilePersistenceWithDataProtection, DataProtectionScope } = require("@azure/msal-node-extensions");
const { PublicClientApplication } = require("@azure/msal-node");

const cachePath = "path/to/cache/file.json";
const dataProtectionScope = DataProtectionScope.CurrentUser;
const optionalEntropy = ""; //specifies password or other additional entropy used to encrypt the data.
const windowsPersistence = await FilePersistenceWithDataProtection.create(cachePath, dataProtectionScope, optionalEntropy);
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(windowsPersistence);
                    },
                });

cachePath es la ruta de acceso en el sistema de archivos donde se almacenará el archivo de caché cifrada.
dataProtectionScope especifica el ámbito de la protección de datos, ya sea el usuario actual o la máquina local. No necesita una clave para proteger o desproteger los datos. Si configura el ámbito como CurrentUser, solo las aplicaciones que se ejecuten con sus credenciales podrán desproteger los datos; sin embargo, eso significa que cualquier aplicación que se ejecute con sus credenciales podrá acceder a los datos protegidos. Si establece el ámbito en LocalMachine, cualquier aplicación de plena confianza en el equipo puede desproteger, acceder y modificar los datos.
optionalEntropy especifica la contraseña u otra entropía adicional que se usa para cifrar los datos.

FilePersistenceWithDataProtection usa las API Win32 CryptProtectData y CryptUnprotectData. Para obtener más información sobre dataProtectionScope o optionalEntropy, consulte la documentación de esas API.

const { KeychainPersistence } = require("@azure/msal-node-extensions");

const cachePath = "path/to/cache/file.json";
const serviceName = "test-msal-electron-service";
const accountName = "test-msal-electron-account";
const macPersistence = await KeychainPersistence.create(cachePath, serviceName, accountName);
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(macPersistence);
                    },
                });

El cachePath no es donde se almacenará la caché. En su lugar, las extensiones actualizan este archivo con datos ficticios para actualizar la hora de actualización del archivo, para comprobar si el contenido de la cadena de claves debe cargarse o no. También se usa como ubicación para el archivo de bloqueo. Nombre del servicio en el que se almacena la memoria caché en la cadena de claves. Nombre de cuenta con el que se almacena la memoria caché en la cadena de claves.

const { LibSecretPersistence } = require("@azure/msal-node-extensions");

const cachePath = "path/to/cache/file.json";
const serviceName = "test-msal-electron-service";
const accountName = "test-msal-electron-account";
const linuxPersistence = await LibSecretPersistence.create(cachePath, serviceName, accountName);
// Use the persistence object to initialize an MSAL PublicClientApplication with cachePlugin
const pca = new PublicClientApplication({
                auth: {
                        clientId: "CLIENT_ID_HERE",
                    },
                cache: {
                        cachePlugin: new PersistenceCachePlugin(linuxPersistence);
                    },
                });

La ruta cachePath no es donde se almacenará la caché. En su lugar, las extensiones actualizan este archivo con datos ficticios para actualizar la hora de actualización del archivo, para comprobar si el contenido del servicio secreto (Gnome Keyring por ejemplo) debe cargarse o no. También se usa como ubicación para el archivo de bloqueo.

nombre de servicio con el que la memoria caché se almacena en el servicio secreto.
nombre de cuenta con el que se almacena la memoria caché en el servicio secreto.

Todas las plataformas

Se proporciona una persistencia de archivos sin cifrar, que funciona en todas las plataformas, aunque no se recomienda.

const { FilePersistence } = require("@azure/msal-node-extensions");

const filePath = "path/to/cache/file.json";
const filePersistence = await FilePersistence.create(filePath, loggerOptions);
// Pass the persistence to msal config's cachePlugin
const pca = new PublicClientApplication({
    auth: {
            clientId: "CLIENT_ID_HERE",
        },
    cache: {
            cachePlugin: new PersistenceCachePlugin(filePersistence);
        },
  });

Si no se ha creado el archivo o directorio, FilePersistence.create() creará el archivo y los directorios de la ruta de acceso de forma recursiva. Esto se puede ver en acción en FilePersistence.ts

Pasar opciones de bloqueo al complemento Cache para simultaneidad

Crear el PersistenceCachePlugin, pasando el objeto de persistencia que se creó en el paso anterior.

const { PersistenceCachePlugin } = require("@azure/msal-node-extensions");

const persistenceCachePlugin = new PersistenceCachePlugin(windowsPersistence); // or any of the other ones.

Para admitir el acceso simultáneo por varios procesos, las extensiones usan un bloqueo basado en archivos. Puedes configurar el número de reintentos y el retraso entre reintentos para la adquisición del bloqueo a través de CrossPlatformLockOptions.

const {
  PersistenceCreator,
  PersistenceCachePlugin,
} = require("@azure/msal-node-extensions");

const lockOptions = {
    retryNumber: 100,
    retryDelay: 50
}

const persistence = await PersistenceCreator.createPersistence(persistenceConfiguration);
const persistenceCachePlugin = new PersistenceCachePlugin(persistence, lockOptions); // or any of the other ones
const pca = new PublicClientApplication({
    auth: {
            clientId: "CLIENT_ID_HERE",
        },
    cache: {
            cachePlugin: persistenceCachePlugin
        },
    });

Establecimiento de PersistenceCachePlugin en la configuración del nodo `PublicClientApplication` MSAL (con un ejemplo)

En resumen, una vez que tenga un PersistenceCachePlugin, puede establecerlo en PublicClientApplicationMSAL Node incluyéndolo en el objeto de configuración, como se muestra a continuación.

import { PublicClientApplication } from "@azure/msal-node";

const publicClientConfig = {
    auth: {
        clientId: "",
        authority: "",
    },
    cache: {
        cachePlugin: persistenceCachePlugin
    },
};

const pca = new PublicClientApplication(publicClientConfig);

Ejemplo (para la aplicación de escritorio Electron node-js):-

authConfig.js:-

const AAD_ENDPOINT_HOST = "https://login.microsoftonline.com/"; // include the trailing slash
const REDIRECT_URI = "ENTER_REDIRECT_URI";

const cachePath = "path/to/cache/file.json";

/*define persistence config based on the appropriate persistence you are using(e.g- FilePersistenceWithDataProtection, generic PersistenceCreateor, etc)*/

//defining persistence config for PersistenceCreator
const persistenceConfiguration = {
    cachePath,
    dataProtectionScope: DataProtectionScope.CurrentUser,
    serviceName: "test-msal-electron-service",
    accountName: "test-msal-electron-account",
    usePlaintextFileOnLinux: false,
}

  const msalConfig = {
    auth: {
        clientId: "CLIENT_ID_HERE",
        authority: `${AAD_ENDPOINT_HOST}TENANT_ID_HERE`,
    },
    cache: {
        cachePlugin: null // set later in main.js as shown above 
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: LogLevel.Verbose,
        },
    },
};
...

module.exports = {
  msalConfig: msalConfig,
  protectedResources: protectedResources,
  REDIRECT_URI: REDIRECT_URI,
  persistenceConfiguration
};

Nota para desarrolladores de Electron

Ejemplo de Electron: este ejemplo muestra cómo integrar la biblioteca msal-node-extensions en su aplicación de Electron que se ha empaquetado con webpack.

Si usa esta extensión para Electron, podría aparecer un error similar al siguiente:

Uncaught Exception:
Error: The module
"<path-to-project>\node_modules\...\dpapi.node" was compiled against a different Node.js version using NODE_MODULE_VERSION 85. This version of Node.js requires NODE_MODULE_VERSION 80. Please try re-compiling or re-installing the module...."

Este error probablemente se deba a las diferencias de versión de Node.js entre el proyecto de Electron y la extensión. Esto se puede solucionar volviendo a compilar el paquete siguiendo estos pasos:

Instale electron-rebuild con el comando npm i -D electron-rebuild si aún no lo tiene instalado.
Quitar el packages-lock.json de tu proyecto si existe
Ejecute ./node_modules/.bin/electron-rebuild:

Samples

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-07-02