Migração de MSAL v2.x para MSAL v3.x

Se és novo na MSAL, deves começar por aqui.

Se vens do MSAL v1.x, deves consultar este guia primeiro para migrar para o MSAL v2.x e depois seguir os próximos passos.

Se vier da MSAL v2.x, pode seguir este guia para atualizar o seu código e usar a MSAL v3.x.

Alterações de grande impacto

Instanciação da aplicação

No MSAL v2.x, criava-se uma instância de aplicação como se seguia:

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

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = new PublicClientApplication(msalConfig);

No MSAL v3.x, também tens de inicializar o objeto de aplicação. Existem várias opções ao seu dispor:

Opção 1

Instanciar um PublicClientApplication objeto e inicializá-lo depois. A initialize função é assíncrona e deve ser resolvida antes de invocar outras APIs MSAL.js.

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

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = new PublicClientApplication(msalConfig);
await msalInstance.initialize();

Opção 2

Invoca o createPublicClientApplication método estático que devolve um objeto inicializado PublicClientApplication . Note que esta função é assíncrona.

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

const msalConfig = {
    auth: {
        clientId: 'your_client_id'
    }
};

const msalInstance = await PublicClientApplication.createPublicClientApplication(msalConfig);

Cache baseada em reclamações

No MSAL v2.x, adicionar declarações a um pedido fará com que, por defeito, seja adicionado à chave de cache do token um hash da cadeia de declarações pedidas. Isto implica que o MSAL 2.x armazena em cache e faz a correspondência de tokens com base nas declarações por defeito. No MSAL v3.x, este comportamento já não é o padrão. O comportamento por defeito da MSAL v3.x é ir à rede para atualizar um token sempre que as reclamações são solicitadas, independentemente de o token ter sido armazenado em cache anteriormente e ainda ser válido. Depois, após ir para a rede, o token recebido sobrescreve o token em cache caso um pedido silencioso sem reivindicações seja executado mais tarde. Para permitir que a cache baseada em reclamações no MSAL v3.x mantenha o mesmo comportamento do MSAL v2.x, os programadores devem usar a cacheOptions.claimsBasedCachingEnabled flag de configuração definida para true no objeto de configuração da Aplicação Cliente:

const msalConfig = {
    auth: {
        ...
    },
    ...
    cache: {
        claimsBasedCachingEnabled: true
    }
}

const msalInstance = new msal.PublicClientApplication(msalConfig);
await msalInstance.initialize();

Todas as outras APIs são retrocompatíveis com MSAL v2.x. Recomenda-se dar uma vista de olhos à amostra padrão para ver um exemplo funcional do MSAL v3.0.

Criptografia

O MSAL v3.x deixa de suportar a criptografia nativa do IE11 window.msCrypto e a Biblioteca de Criptografia JavaScript da Microsoft Research (MSR crypto) window.msrCrypto em favor da API de criptografia nativa do navegador window.crypto. As opções criptográficas config.system.cryptoOptions usadas para a criptografia MSR deixaram igualmente de ser suportadas.

Alterações principais

Suporte de navegador

MSAL.js já não suporta os seguintes navegadores:

• IE 11
• Edge (Legacy)

Dependências do pacote

A versão do TypeScript foi atualizada de 3.8.3 para 4.9.5.

Opções do compilador

As versões do módulo/alvo foram atualizadas de es6/es5 para es2020/es2020, respetivamente.

CDN

MSAL.js já não é alojada numa CDN. Consulte este documento para mais detalhes.