Armazenamento em cache no MSAL.js

Quando a MSAL adquire um token, ele o armazena em cache para uso futuro. O MSAL gerencia os tempos de vida dos tokens e a renovação deles para você. A acquireTokenSilent() API recupera tokens de acesso do cache para uma determinada conta e os renova, se necessário.

Armazenamento em cache

Você pode configurar o local de armazenamento em cache por meio do objeto de configuração usado para instanciar a MSAL:

import { PublicClientApplication, BrowserCacheLocation } from "@azure/msal-browser";

const pca = new PublicClientApplication({
    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),
        redirectUri: "/"
    },
    cache: {
       cacheLocation: BrowserCacheLocation.SessionStorage // "sessionStorage"
    }
});

Por padrão, a MSAL armazena os vários artefatos de autenticação obtidos do IdP no armazenamento do navegador usando a API de Armazenamento da Web compatível com todos os navegadores modernos. Assim, a MSAL oferece dois métodos de armazenamento persistente: sessionStorage (padrão) e localStorage. Além disso, a MSAL fornece memoryStorage uma opção que permite que você não armazene o cache no armazenamento do navegador.

A escolha entre diferentes locais de armazenamento reflete uma compensação entre uma melhor experiência do usuário versus maior segurança. Como a tabela acima indica, o armazenamento local resulta na melhor experiência do usuário possível, enquanto o armazenamento de memória fornece a melhor segurança, pois nenhuma informação confidencial é armazenada no armazenamento do navegador. Consulte a seção sobre segurança e artefatos armazenados em cache abaixo para obter mais informações.

Notas de LocalStorage

A partir da v4, se você estiver usando o local do localStorage cache, os artefatos de autenticação serão criptografados, a menos que o usuário selecione "Manter-me conectado" durante a entrada. O algoritmo de criptografia usado é AES-GCM usando HKDF para derivar a chave. A chave base é armazenada em um cookie de sessão intitulado msal.cache.encryption.

Esse cookie é removido automaticamente quando a instância do navegador (não a guia) é fechada, tornando impossível descriptografar quaisquer artefatos de autenticação após o término da sessão. Esses artefatos de autenticação expirados são removidos na próxima vez que a MSAL for inicializada e o usuário talvez precise se autenticar novamente. O local localStorage ainda fornece persistência de cache entre guias para todos os usuários, mas só é persistido entre sessões do navegador para os usuários que selecionaram "Manter-me conectado" (KMSI).

Armazenamento de cookies

O Navegador MSAL pode ser configurado para usar cookies para armazenar artefatos de autenticação temporária. Essa opção permite que você dê suporte a navegadores que podem limpar o armazenamento local/de sessão durante fluxos de logon baseados em redirecionamento (por exemplo, Internet Explorer, Firefox no modo privado). Observe que, quando essa opção é escolhida, os próprios tokens ainda são armazenados no navegador ou no armazenamento de memória. Consulte a configuração para obter mais informações.

Segurança

Consideramos o armazenamento de sessão/local seguro, desde que seu aplicativo não tenha vulnerabilidades de cross-site scripting (XSS) e outras vulnerabilidades relacionadas. Consulte a Guia de Referência Rápida de Prevenção contra XSS da OWASP para proteger suas aplicações contra XSS. Se ainda tiver preocupações, recomendamos usar a opção memoryStorage.

Artefatos armazenados em cache

Para facilitar a aquisição eficiente de tokens, mantendo uma boa experiência de usuário, a MSAL armazena em cache vários artefatos resultantes de suas chamadas à API. Veja abaixo um resumo das entidades no cache MSAL:

• Artefatos duráveis (que permanecem após a solicitação -consulte também: ciclos de vida do token)
  • tokens de acesso
  • tokens de id
  • tokens de atualização
  • contas
• Artefatos efêmeros (limitados ao tempo de vida da solicitação)
  • metadados de solicitação (por exemplo, estado, nonce, autoridade)
  • Erros
  • status da interação
• Telemetria
  • solicitação com falha anterior
  • dados de desempenho

substituição temporaryCacheLocation

Ao usar MSAL.js com a configuração padrão em um cenário em que o usuário é redirecionado após a autenticação bem-sucedida em uma nova janela ou guia, o código de autorização OAuth 2.0 com fluxo PKCE será interrompido. Nesse caso, a janela ou guia original em que o estado de autenticação (verificador de código e desafio) é armazenado, será perdida e o fluxo de autenticação falhará.

Para lidar com esse cenário, você pode configurar a MSAL para usar localStorage como o local do cache substituindo a temporaryCacheLocation propriedade de configuração. Isso permite que o código de verificação e o desafio sejam armazenados no localStorage do navegador, que permanece em múltiplas guias e janelas.

Persistência de cache durante atualizações e reversões do MSAL.js

Ocasionalmente, MSAL.js precisa fazer alterações na forma dos artefatos armazenados em cache para dar suporte a novos requisitos, recursos ou correções de bug. Sempre que possível, essas alterações são feitas de maneira compatível com versões anteriores para garantir que, quando um aplicativo é atualizado para uma nova versão ou reverta para uma versão mais antiga, o cache presente no navegador de um usuário ainda pode ser usado. No entanto, isso nem sempre é possível e você pode acabar em um estado em que várias cópias do cache existem simultaneamente, uma usada pela versão atual do MSAL.js em execução e outra que foi gravada pela versão usada antes da atualização. Isso é feito para permitir que os aplicativos revertam normalmente, se necessário. Na grande maioria das atualizações, MSAL.js migra qualquer cache existente para o novo formato para uma experiência de atualização perfeita. Em casos raros, como a atualização da v3 para a v4, isso pode não ser possível devido aos requisitos de segurança ou privacidade, e isso sempre resulta em um aumento de versão principal.

Quando uma alteração de cache interruptiva é feita, o cache mais antigo é mantido por cinco dias, por padrão, para permitir uma reversão, se necessário. O período durante o qual o cache antigo é mantido pode ser configurado usando a configuração de cache cacheRetentionDays em PublicClientApplication. Se o cache não tiver sido usado ativamente dentro desse tempo, ele será limpo na próxima vez que MSAL.js for inicializado. Além disso, se você não prever a necessidade de reversão, poderá definir esse valor como 0 para indicar que o cache antigo sempre deve ser removido imediatamente após a atualização para uma nova versão do MSAL.js. Por outro lado, se você tiver uma janela de implantação mais longa para atualizações, poderá optar por definir um valor maior para isso.

const config = {
    auth: {
        clientId: "<your-client-id>"
    },
    cache: {
        cacheLocation: "localStorage",
        cacheRetentionDays: 0 // Set this to the number of days you want old cache to be preserved in the event a rollback is needed (Default 5 days)
    }
}

const pca = new PublicClientApplication(config);
await pca.initialize();

Observações

• Não recomendamos que os aplicativos tenham lógica de negócios dependente do uso direto de entidades no cache. Em vez disso, use a API MSAL apropriada quando precisar adquirir tokens ou recuperar contas.
• As chaves usadas para criptografar tokens pop (prova de posse) são armazenadas usando uma combinação de API IndexedDB e armazenamento de memória. Para obter mais informações, consulte access-token-proof-of-possession.

Mais informações

• Adquirir e armazenar tokens em cache usando o Biblioteca do Microsoft Authenticator