Armazenamento em cache no MSAL.js

Quando a MSAL adquire um token, armazena-o em cache para uso futuro. MSAL gere o tempo de vida dos tokens e a respetiva renovação por si. A acquireTokenSilent() API recupera tokens de acesso da cache de uma determinada conta e renova-os se necessário.

Armazenamento em cache

Pode configurar a localização de armazenamento da cache através do objeto de configuração que é usado para instanciar o 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 defeito, o MSAL armazena os vários artefactos de autenticação que obtém do IdP no armazenamento do navegador através da Web Storage API, suportada por todos os navegadores modernos. Assim, a MSAL oferece dois métodos de armazenamento persistente: sessionStorage (por defeito) e localStorage. Além disso, o MSAL oferece memoryStorage uma opção que permite optar por não armazenar a cache no armazenamento do navegador.

A escolha entre diferentes locais de armazenamento reflete um equilíbrio entre melhor experiência do utilizador e maior segurança. Como indica a tabela acima, o armazenamento local resulta na melhor experiência de utilizador possível, enquanto o armazenamento de memória oferece a melhor segurança, uma vez que nenhuma informação sensível é armazenada no armazenamento do navegador. Consulte a secção sobre segurança e artefactos em cache abaixo para mais informações.

Notas do LocalStorage

A partir da v4, se estiver a utilizar a localização da cache localStorage, os artefactos de autenticação são cifrados, a menos que o utilizador selecione "Manter sessão iniciada" ao iniciar sessão. O algoritmo de encriptação utilizado é AES-GCM usando HKDF para obter a chave. A chave base é armazenada num cookie de sessão intitulado msal.cache.encryption.

Este cookie é automaticamente removido quando a instância do navegador (não o tab) é fechada, tornando impossível desencriptar quaisquer artefactos de autenticação após o fim da sessão. Estes artefactos de autenticação expirados são removidos na próxima inicialização do MSAL e o utilizador pode precisar de se autenticar novamente. A localStorage localização continua a fornecer persistência de cache cruzada para todos os utilizadores, mas só persiste entre as sessões do navegador para utilizadores que selecionaram "Manter-me iniciado" (KMSI).

Armazenamento de cookies

O MSAL Browser pode ser configurado para usar cookies para armazenar artefactos temporários de autenticação. Esta opção permite-lhe suportar navegadores que podem limpar armazenamento local/sessão durante fluxos de login baseados em redirecionamento (por exemplo, Internet Explorer, Firefox em modo privado). Note-se que, quando esta opção é escolhida, os próprios tokens continuam armazenados no navegador ou na memória. Por favor, consulte a configuração para mais informações.

Segurança

Consideramos o armazenamento de sessão/local seguro desde que a sua aplicação não tenha cross-site scripting (XSS) e vulnerabilidades relacionadas. Consulte a Folha Informativa de Prevenção de XSS da OWASP para proteger as suas aplicações contra ataques XSS. Se ainda estiver preocupado, recomendamos que use a opção memoryStorage em alternativa.

Artefactos armazenados em cache

Para facilitar a aquisição eficiente de tokens mantendo uma boa experiência de utilizador, o MSAL armazena em cache vários artefactos resultantes das suas chamadas à API. Abaixo está um resumo das entidades na cache MSAL:

• Artefactos duradouros (que perduram após a solicitação -ver também: tempo de vida dos tokens)
  • Tokens de acesso
  • Fichas id
  • Tokens de atualização
  • accounts
• Artefactos efémeros (limitado à duração do pedido)
  • Solicitar metadados (por exemplo, estado, nonce, autoridade)
  • erros
  • Estado de interação
• Telemetria
  • Pedido anterior falhado
  • Dados de desempenho

substituição de temporaryCacheLocation

Ao usar MSAL.js com a configuração padrão num cenário em que o utilizador é redirecionado após autenticação bem-sucedida numa nova janela ou separador, o Código de Autorização OAuth 2.0 com fluxo PKCE será interrompido. Neste caso, a janela ou aba original onde o estado de autenticação (verificador de código e desafio) está armazenado será perdida e o fluxo de autenticação falhará.

Para lidar com este cenário, pode configurar o MSAL para utilizar localStorage como a localização da cache, redefinindo a propriedade de configuração temporaryCacheLocation. Isto permite que o verificador de código e o desafio sejam armazenados no localStorage do navegador, o qual se mantém entre vários separadores e janelas.

Persistência da cache durante atualizações e rollbacks do MSAL.js

Por vezes, MSAL.js precisa de fazer alterações na forma dos artefactos em cache para suportar novos requisitos, funcionalidades ou correções de bugs. Sempre que possível, estas alterações são feitas de forma retrocompatível para garantir que, quando uma aplicação atualiza para uma nova versão ou reverte para uma versão anterior, a cache presente no navegador do utilizador ainda possa ser utilizada. No entanto, isso nem sempre é possível e podes acabar num estado em que existem múltiplas cópias da cache em simultâneo, uma usada pela versão atual do MSAL.js a correr e outra que foi escrita pela versão usada antes da atualização. Isto é feito para permitir que as aplicações recuem de forma controlada, 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 fluida. Em casos raros, como na atualização da v3 para a v4, isso pode não ser possível devido a requisitos de segurança ou privacidade, e isso resulta sempre numa grande melhoria da versão.

Quando é feita uma alteração na cache que falha, a cache antiga é mantida durante 5 dias, por defeito, para permitir um rollback se necessário. O tempo em que a cache antiga é mantida pode ser configurada usando a cacheRetentionDays configuração da cache em PublicClientApplication. Se a cache não tiver sido usada ativamente nesse período, é apagada na próxima MSAL.js inicialização. Além disso, se não prevê necessidade de reverter, pode definir este valor como 0 para indicar que a cache antiga deve ser sempre removida imediatamente ao atualizar para uma nova versão do MSAL.js. Por outro lado, se tiver uma janela de implementação mais longa para atualizações, pode optar por definir este valor para um valor mais longo.

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 as aplicações tenham lógica de negócio dependente do uso direto de entidades na cache. Em vez disso, use a API MSAL apropriada quando precisar de adquirir tokens ou recuperar contas.
• As chaves usadas para encriptar tokens de prova de posse (PoP) são armazenadas usando uma combinação da API IndexedDB e armazenamento de memória. Para mais informações, consulte access-token-proof-of-possession.

Mais informações

• Adquirir e colocar tokens em cache com a Biblioteca de Autenticação da Microsoft