Extensões de Autenticação Microsoft para Node

As Extensões de Autenticação da Microsoft para Node oferecem mecanismos seguros para que as aplicações clientes possam realizar serialização e persistência da cache de tokens entre plataformas.

MSAL Node exige que os programadores implementem a sua própria lógica para persistir a cache do token. As extensões MSAL Node visam fornecer uma implementação robusta, segura e configurável de permanência de cache de token em Windows, Mac e Linux para aplicações clientes públicas (clientes de ambiente de trabalho, aplicações CLI, etc). Fornece mecanismos para encriptar e aceder à cache de tokens por múltiplos processos em simultâneo.

As plataformas suportadas são Windows, Mac e Linux:

Windows - DPAPI é usado para encriptação.
MAC - O Chaveiro MAC é usado através do npm keytar.
Linux - LibSecret é usado para armazenar no "Serviço Secreto" através do npm keytar.

Code

Criação da camada de persistência

A API para criar a camada de persistência vai variar consoante a plataforma que pretendes.

Em alternativa, podes usar a createPersistence API do PersistenceCreator porque é um wrapper genérico e seleciona o método de persistência apropriado com base na plataforma/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);
                    },
                });

Alternativamente, pode usar as opções específicas da plataforma abaixo:


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 é o caminho no sistema de ficheiros onde o ficheiro de cache encriptado será armazenado.
dataProtectionScope especifica o âmbito da proteção de dados, seja do utilizador atual ou da máquina local. Não precisa de uma chave para proteger ou desproteger os dados. Se definir o âmbito para CurrentUser, só as aplicações a correr nas suas credenciais podem desproteger os dados; No entanto, isso significa que qualquer aplicação a correr nas suas credenciais pode aceder aos dados protegidos. Se definir o âmbito para LocalMachine, qualquer aplicação de confiança total no computador pode desproteger, aceder e modificar os dados.
optionalEntropy especifica a palavra-passe ou outra entropia adicional usada para encriptar os dados.

O FilePersistenceWithDataProtection utiliza as APIs do Win32 CryptProtectData e CryptUnprotectData. Para mais informações sobre dataProtectionScope, ou optionalEntropy, consulte a documentação dessas APIs.

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

O cachePath não é o local onde a cache será armazenada. Em vez disso, as extensões atualizam este ficheiro com dados fictícios para atualizar o tempo de atualização do ficheiro, para verificar se o conteúdo do porta-chaves deve ser carregado ou não. Também é usado como a localização para o ficheiro de bloqueio. O nome do serviço com o qual a cache é armazenada no Keychain. O nome da conta sob o qual a cache está armazenada no porta-chaves.

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

cachePath não é o local onde a cache será armazenada. Em vez disso, as extensões atualizam este ficheiro com dados fictícios para atualizar o tempo de atualização do ficheiro, para verificar se o conteúdo do serviço secreto (como o Gnome Keyring) deve ser carregado ou não. É também usada como localização para o ficheiro de bloqueio.

nome do serviço sob o qual a cache é armazenada pelo serviço secreto.
Nome da conta sob o qual o cache é armazenado no Serviço Secreto.

Todas as plataformas

Uma persistência de ficheiros não encriptados, que funciona em todas as plataformas, é fornecida por conveniência, embora não seja recomendada.

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

Se o ficheiro ou diretório não tiver sido criado, FilePersistence.create() irá criar o ficheiro e quaisquer diretórios no caminho de forma recursiva. Isto pode ver-se em ação em FilePersistence.ts

Passar opções de bloqueio para o plugin Cache para concorrência

Crie o PersistenceCachePlugin, passando o objeto de persistência que foi criado no passo anterior.

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

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

Para suportar o acesso concorrente por múltiplos processos, as extensões utilizam um bloqueio baseado em ficheiros. Pode configurar o número de tentativas e o atraso entre tentativas para a aquisição do bloqueio atravé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
        },
    });

Configurar o PersistenceCachePlugin na configuração do MSAL Node `PublicClientApplication` (com um exemplo)

Para resumir, uma vez que se tenha um PersistenceCachePlugin, isso pode ser definido no Nó PublicClientApplicationMSAL , definindo-o como parte do objeto de configuração conforme mostrado abaixo.

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

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

const pca = new PublicClientApplication(publicClientConfig);

Exemplo (para a aplicação para computador 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 Programadores de Electron

Exemplo do Electron: Este exemplo mostra como integrar a biblioteca msal-node-extensions na sua aplicação Electron que foi empacotada com o webpack.

Se estiver a usar esta extensão para o Electron, pode enfrentar um erro semelhante a este:

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 erro deve-se provavelmente a diferenças Node.js versão entre o projeto Electron e a extensão. Isto pode ser tratado reconstruindo o pacote com os seguintes passos:

Instala electron-rebuild com o comando npm i -D electron-rebuild se ainda não o tiveres instalado.
Remova packages-lock.json do seu projeto se ele existir
Executar ./node_modules/.bin/electron-rebuild

Samples

Comentários

Esta página foi útil?

Last updated on 2026-07-02