Armazenamento em cache de tokens no MSAL Node

Quando o Nó MSAL adquire um token, ele o armazena em cache na memória para uso futuro. O MSAL Node gerencia o tempo de vida e a renovação do token para você. APIs como acquireTokenSilent() recupera tokens de acesso do cache para uma determinada conta:

A MSAL não expõe tokens de atualização por motivos de segurança. Consulte as perguntas frequentes sobre como obter os tokens de atualização.

Usar segredos de cliente com segurança

Os segredos do cliente nunca devem ser codificados. O pacote dotenv npm pode ser usado para armazenar segredos em um arquivo .env (localizado no diretório raiz do projeto) que deve ser incluído no .gitignore para evitar uploads acidentais dos segredos.

const msal = require('@azure/msal-node');
require('dotenv').config(); // process.env now has the values defined in a .env file

// Create msal application object
const cca = new msal.ConfidentialClientApplication({
    auth: {
        clientId: "Enter_the_Application_Id_Here", // e.g. "00001111-aaaa-2222-bbbb-3333cccc4444" (guid)
        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here", // e.g. "common" or your tenantId (guid)
        clientSecret: process.env.clientSecret // obtained during app registration
    }
});

/**
* acquireToken* APIs return an account object containing the "homeAccountId"
* you should keep a record of this in your app and use it later on when calling acquireTokenSilent
*/
const someUserHomeAccountId = "Enter_User_Home_Account_Id";

const msalTokenCache = cca.getTokenCache();
const account = await msalTokenCache.getAccountByHomeId(someUserHomeAccountId);

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

cca.acquireTokenSilent(silentTokenRequest).then((response) => {
    // do something with response
}).catch((error) => {
    // catch and handle errors
});

Na produção, você provavelmente vai querer serializar e persistir o cache de tokens. Dependendo do tipo de aplicativo, você pode:

  • Aplicativos de área de trabalho, aplicativos de console (aplicativos cliente público (PCA)):
    • Use MSAL Node Extensions, que fornece soluções de persistência e criptografia de dados em repouso no Windows, no Linux e no macOS
  • Aplicativos Web, APIs Web, aplicativos daemon (aplicativos cliente confidenciais (CCA)):
    • O cache de tokens na memória da MSAL não é escalável para produção. Use o padrão de cache distribuído de tokens para persistir o cache no ambiente de armazenamento de sua escolha (Redis, MongoDB, bancos de dados SQL etc. — tenha em mente que você pode usá-los em conjunto, e.g. um cache em memória do tipo Redis como primeira camada de persistência e um banco de dados SQL como segunda camada, mais estável, de persistência)

Cache na memória

A MSAL mantém um cache na memória. O cache na memória é representativo do estado do cache do aplicativo. O tempo de vida do cache na memória é o mesmo que o objeto de aplicativo MSAL. Se o processo usando MSAL for reiniciado, o cache será apagado quando o ciclo de vida do processo for concluído. Se o cache na memória estiver vazio e não houver nenhum cache persistente do qual restaurar o cache, os usuários precisarão se autenticar novamente. Quando isso acontece, se o usuário ainda tiver uma sessão ativa com Microsoft Entra ID, ele poderá se autenticar novamente sem nenhum prompt, no entanto, isso ainda degrada a experiência do usuário. Cenários de serviço a serviço (ou seja, fluxo de credenciais do cliente, fluxo On-Behalf-Of) também sofrem, porque obter um token do Microsoft Entra ID envolve solicitações HTTP e é muito mais lento do que obter um token do cache.

Observe que o cache na memória não é escalonável para aplicativos do lado do servidor e o desempenho será prejudicado depois de manter alguns 100 tokens em cache. Para cenários de aplicativo Web e API Web, isso se aproxima de atender alguns 100 usuários. Para cenários de aplicativo daemon usando a concessão de credenciais do cliente para chamar outros aplicativos, isso significa alguns 100 locatários. Veja o desempenho abaixo para obter mais informações.

⚠️ Recomendamos manter o cache com criptografia para todos os aplicativos de produção para segurança e longevidade de cache desejada. Se você optar por não persistir o cache, a interface TokenCache ainda estará disponível para acessar as entidades armazenadas em cache.

Cache persistente

O Nó MSAL aciona eventos quando o cache na memória é acessado e os aplicativos podem escolher se devem persistir o cache (veja: TokenCacheContext) (por exemplo, para um arquivo, um banco de dados SQL e etc.). Isso constitui duas ações:

  1. Carregue o cache do armazenamento persistente para a memória da MSAL antes de acessar o cache
  2. Se o cache na memória tiver sido alterado desde o último acesso, salve o cache de volta para persistência

Para persistir o cache, a MSAL aceita um plug-in de cache personalizado na configuração. Esse plug-in deve implementar a interface ICachePlugin :

interface ICachePlugin {
    beforeCacheAccess: (tokenCacheContext: TokenCacheContext) => Promise<void>;
    afterCacheAccess: (tokenCacheContext: TokenCacheContext) => Promise<void>;
}

Uma implementação básica da ICachePlugin interface pode ter a seguinte aparência (consulte também desempenho e segurança se você estiver criando um aplicativo do lado do servidor):

class MyCachePlugin implements ICachePlugin {
    private client: ICacheClient;

    constructor(client: ICacheClient) {
        this.client = client; // client object to access the persistent cache
    }

    public async beforeCacheAccess(cacheContext: TokenCacheContext): Promise<void> {
        const cacheData = await this.client.get(); // get the cache from persistence
        cacheContext.tokenCache.deserialize(cacheData); // deserialize it to in-memory cache
    }

    public async afterCacheAccess(cacheContext: TokenCacheContext): Promise<void> {
        if (cacheContext.cacheHasChanged) {
            await this.client.set(cacheContext.tokenCache.serialize()); // deserialize in-memory cache to persistence
        }
    }
}
  • Se você estiver desenvolvendo um aplicativo cliente público, as Extensões de Nó MSAL lidarão com isso para você.
  • Se você estiver desenvolvendo um aplicativo cliente confidencial, deverá manter o cache por meio de um serviço separado, já que uma única instância de cache por servidor não é adequada para um ambiente de nuvem com muitos servidores e instâncias de aplicativo.

É altamente recomendável criptografar o cache de token ao persistê-lo no disco. Para aplicativos de cliente público, isso é disponibilizado pronto para uso com o MSAL Node Extensions. No entanto, para clientes confidenciais, você é responsável por criar uma solução de criptografia apropriada.

Desempenho e segurança

Em aplicativos cliente públicos, as Extensões de Nó MSAL garantem desempenho e segurança para você.

Em aplicativos cliente confidenciais que lidam com usuários (aplicativos Web que conectam usuários e chamam APIs Web, e APIs Web que chamam APIs Web subsequentes), pode haver muitos usuários ativos simultaneamente em um determinado aplicativo. Nossa recomendação é serializar um blob de cache (consulte CacheRecord) por usuário. Isso ajudaria a dimensionar o cache em um sistema distribuído. Use uma chave para particionar o cache (ou seja, chave de partição), como:

  • Para aplicativos Web: <userObjectId>.<tenantId> (ou seja homeAccountId)
  • Para aplicativos daemon multilocatário usando a concessão de credenciais do cliente: <clientId>.<tenantId>
  • Para APIs da Web que chamam outras APIs da Web usando OBO: hash do token de acesso recebido (ou seja, oboAssertion) — o token que será posteriormente trocado por um token OBO

⚠️ Confira o desempenho para obter mais informações sobre como monitorar o uso e evitar um desempenho ruim.

Aplicativos Web

Como os aplicativos Web são voltados para o usuário e geralmente dependem de sessões para acompanhar cada usuário, a chave de partição apropriada para o cache geralmente é armazenada nos dados da sessão e precisa ser recuperada antes que a pesquisa de cache possa ocorrer. Para ajudar com isso, o MsAL Node fornece a classe DistributedCachePlugin , que implementa o ICachePlugin. Uma instância de DistributedCachePlugin requer:

  • uma interface de cliente (ICacheClient), que implementa operações get e set no servidor de persistência (Redis, MySQL etc.).
  • um gerenciador de partições (IPartitionManager), para ler e gravar em cache em relação a uma determinada ID de sessão.

Consulte o aplicativo Web usando DistributedCachePlugin para obter uma implementação de exemplo.

Consulte também

Confira os exemplos abaixo para saber mais sobre como lidar com o cache em aplicativos de nó MSAL:

  • Last updated on