Migrar do MSAL Browser v4 para v5

Se você for novo na MSAL, comece aqui.

Se você estiver vindo da MSAL v2, deverá verificar este guia primeiro para migrar para a MSAL v3. Se você estiver vindo da MSAL v3, deverá verificar este guia primeiro para migrar para a MSAL v4 e, em seguida, seguir as próximas etapas.

Se você estiver vindo da MSAL v4, siga este guia para atualizar seu código para usar a MSAL v5.

Alterações significativas na API

O tipo de retorno SignedHttpRequest.removeKeys foi alterado

A removeKeys função na SignedHttpRequest classe agora retorna Promise<void> em vez de Promise<boolean>. A resolução bem-sucedida da promessa agora é equivalente ao que antes era um valor de retorno de true. Se ocorrer uma falha, ela agora será gerada como um erro em vez de retornar false.

// BEFORE
const shr = new SignedHttpRequest(shrParameters, shrOptions);
const result = await shr.removeKeys(thumbprint);
if (result) {
    // do something on success
} else {
    // do something on failure
}

// AFTER
const shr = new SignedHttpRequest(shrParameters, shrOptions);
await shr
    .removeKeys(thumbprint)
    .then(() => {
        // do something on success
    })
    .catch((e) => {
        // do something on failure
        console.log(e);
    });

TokenCache e loadExternalTokens

A API JS da MSAL para loadExternalTokens é modificada. As alterações incluem:

• TokenCache objeto e getTokenCache() foram removidos
• A loadExternalTokens() API agora é uma exportação separada e requer Configuration como parâmetro

// BEFORE

const pca = new PublicClientApplication(config);
await pca
    .getTokenCache()
    .loadExternalTokens(silentRequest, serverResponse, loadTokenOptions);

//AFTER

await loadExternalTokens(
    config,
    silentRequest,
    serverResponse,
    loadTokenOptions
);

handleRedirectPromise A assinatura da API foi alterada

Anteriormente, PublicClientApplication.handleRedirectPromise aceitava um parâmetro de hash opcional. Um novo tipo de opções chamado HandleRedirectPromiseOptions foi introduzido. A partir do MSAL Browser v5, um objeto opcional com tipo HandleRedirectPromiseOptions é o único parâmetro handleRedirectPromise() aceito.

// BEFORE
const hash = window.location.hash; // Arbitrary example value
pca.handleRedirectPromise(hash);

// AFTER
pca.handleRedirectPromise({
    hash: window.location.hash, // Option nested inside a `HandleRedirectPromiseOptions` object
    navigateToLoginRequestUrl: true, // Additional option
});

Remoção de algumas funções em PublicClientApplication

As seguintes funções em PublicClientApplication foram removidas:

1. enableAccountStorageEvents() e disableAccountStorageEvents(): os eventos de armazenamento da conta agora estão sempre habilitados. Essas chamadas de função não são mais necessárias.

2. getAccountByHomeId(), getAccountByLocalId()e getAccountByUsername(): use getAccount() em vez disso.

   // BEFORE
   const account1 = accountManager.getAccountByHomeId(yourHomeAccountId);
   const account2 = accountManager.getAccountByLocalId(yourLocalAccountId);
   const account3 = accountManager.getAccountByUsername(yourUsername);
   
   // AFTER
   const account1 = accountManager.getAccount({
       homeAccountId: yourHomeAccountId,
   });
   const account2 = accountManager.getAccount({
       localAccountId: yourLocalAccountId,
   });
   const account3 = accountManager.getAccount({ username: yourUsername });
   

3. logout(): use logoutRedirect() ou logoutPopup() em vez disso.

Remoção de startPerformanceMeasurement()

startPerformanceMeasurement() foi removido. Use startMeasurement() em seu lugar.

Remoção de PublicClientNext

A PublicClientNext classe e seu método createPublicClientApplication() estático foram removidos no MSAL v5. Você deve usar uma das seguintes alternativas, dependendo dos requisitos do aplicativo:

• PublicClientApplication: use-o para cenários de aplicativo único padrão. Esse é o uso padrão e mais comum.
• createNestablePublicClientApplication: use isso se precisar dar suporte a aplicativos aninhados (NAA). Esta função retorna automaticamente a um PublicClientApplication padrão se a ponte de aplicativo aninhado estiver indisponível ou se o Hub não estiver configurado para oferecer suporte à autenticação de aplicativo aninhado. Consulte Configuração de Aplicativo Aninhado para obter mais detalhes.
• createStandardPublicClientApplication: use isso para instanciar e inicializar uma instância de PublicClientApplication padrão (não NAA).

Exemplo de migração

// BEFORE (using PublicClientNext)
import { PublicClientNext } from "@azure/msal-browser";

const pca = PublicClientNext.createPublicClientApplication(config);

// AFTER (standard usage)
import { PublicClientApplication } from "@azure/msal-browser";

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

// AFTER (nested app support)
import { createNestablePublicClientApplication } from "@azure/msal-browser";

const pca = await createNestablePublicClientApplication(config);

// AFTER (standard)
import { createStandardPublicClientApplication } from "@azure/msal-browser";

const pca = await createStandardPublicClientApplication(config);

Para a maioria das aplicações, substituir PublicClientNext.createPublicClientApplication(config) por new PublicClientApplication(config) é suficiente. Se você usou anteriormente a opção supportsNestedAppAuth de configuração, migre para createNestablePublicClientApplication(config) .

Remoção da função estática PublicClientApplication.createPublicClientApplication

A função estática createPublicClientApplication em PublicClientApplication foi removida e substituída por uma createStandardPublicClientApplication exportada separadamente.

Exemplo de migração

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

const pca = await PublicClientApplication.createPublicClientApplication(config);

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

const pca = await createStandardPublicClientApplication(config);

Alterações de configuração

Alterações em BrowserAuthOptions

1. O skipAuthorityMetadataCache parâmetro foi removido do BrowserAuthOptions na Configuração.

2. O protocolMode parâmetro foi movido para SystemOptions em vez de BrowserAuthOptions na Configuração.

3. O parâmetro supportsNestedAppAuth foi removido. Em vez disso, use a createNestablePublicClientApplication API para aplicativos aninhados. Leia mais sobre aplicativos aninhados aqui.

4. O parâmetro navigateTologinRequestUrl foi removido de BrowserAuthOptions em Configuration e agora pode ser passado em um objeto de opções como parâmetro na chamada de handleRedirectPromise:

   pca.handleRedirectPromise({ navigateToLoginRequestUrl: false });
   

5. O parâmetro encodeExtraQueryParams foi removido. Todos os parâmetros de consulta extras são codificados.

6. O parâmetro supportsNestedAppAuth foi removido. Use createNestablePublicClientApplication() em seu lugar.

       // BEFORE
       const pca = new PublicClientApplication({
           auth: {
               clientId: "your-client-id",
               authority: "https://login.microsoftonline.com/common"
               supportsNestedAppAuth: true
           },
       });
   
       // AFTER
       const pca = await createNestablePublicClientApplication({
           auth: {
               clientId: "your-client-id",
               authority: "https://login.microsoftonline.com/common"
           }
       });
   

7. O OIDCOptions parâmetro agora usa um ResponseMode em vez de um ServerResponseType. ResponseMode.QUERY Use no lugar de ServerResponseType.QUERY e ResponseMode.FRAGMENT em vez de ServerResponseType.FRAGMENT.

Alterações em CacheOptions

Os seguintes parâmetros foram preteridos no MSAL Browser v4 e foram removidos na CacheOptions v5:

1. temporaryCacheLocation
2. claimsBasedCachingEnabled - Os tokens de acesso não são mais armazenados com base nas declarações solicitadas.
3. storeAuthStateInCookie
4. secureCookies - Todos os cookies agora só são enviados com segurança por HTTPS.
5. cacheMigrationEnabled

SystemOptions

1. O parâmetro protocolMode foi movido de BrowserAuthOptions para SystemOptions em Configuração. Não há alterações em suas opções ou funcionalidades.
2. O parâmetro navigateFrameWait foi removido. Isso era necessário anteriormente por navegadores mais antigos que não têm mais suporte do MSAL.js.
3. Os parâmetros iframeHashTimeout e windowHashTimeout foram substituídos por iframeBridgeTimeout e popupBridgeTimeout, respectivamente. Esses tempos limite agora controlam por quanto tempo esperar por uma resposta da ponte de redirecionamento por meio da API BroadcastChannel.

asyncPopups

O asyncPopups parâmetro foi renomeado para navigatePopups dentro SystemOptions e as opções revertidas. Isso define se os pop-ups são abertos e acessados posteriormente. Quando definido como verdadeiro, pop-ups em branco são abertos e navegam para o domínio de login. Quando configurado como `false`, os pop-ups são abertos diretamente no domínio de login. Isso pode ser definido como falso em cenários em que about:blank não tem suporte, por exemplo, aplicativos para desktop ou aplicativos web progressivos.

Consulte o documento de configuração para obter mais detalhes.

Alterações na solicitação

Remoção do onRedirectNavigate parâmetro

O parâmetro onRedirectNavigateé compatível apenas com o objeto Configuration daqui para frente e é removido dos objetos RedirectRequest e EndSessionRequest. Certifique-se de defini-lo na configuração do MSAL caso precise usá-lo.

Consolidação de parâmetros de solicitação extra

Os seguintes parâmetros de solicitação foram removidos:

• authorizePostBodyParams
• tokenBodyParameters
• tokenQueryParameters

Para simplificar os parâmetros de solicitação extras, os parâmetros extras genéricos devem entrar na nova extraParameters opção de solicitação. Quando extraParameters são definidos em uma solicitação, eles são enviados em todas as chamadas ao serviço de token, na string de consulta da URL ou no corpo da solicitação, dependendo do httpMethod configurado (o padrão é GET) na solicitação. Para enviar parâmetros extras que DEVEM ir na cadeia de caracteres de consulta de URL, extraQueryParameters ainda está disponível.

Exemplo de solicitação v4 (anterior):

// Example of a GET request with extra parameters
const authRequest = {
    scopes: ["SAMPLE_SCOPE"],
    extraQueryParamters: {
        "dc": "DC_VALUE" // This was sent on the query string on GET /authorize
    },
    tokenBodyParameters: {
        "extra_parameters_assertion": "ASSERTION_VALUE" // This was sent on the POST body to /token
    },
    tokenQueryParamters: {
        "slice": "SLICE_VALUE" // This was sent on the query string on POST /token
    }
}

// Example of a POST request with extra parameters
const authRequest = {
    scopes: ["SAMPLE_SCOPE"],
    httpMethod: "POST", // default is "GET" -> Determines method for "/authorize" call. Calls to "/token" are always POST
    extraQueryParamters: {
        "dc": "DC_VALUE" // This was sent on the query string on POST /authorize
    },
    authorizePostBodyParameters: {
        "extra_parameters_assertion": "ASSERTION_VALUE", // This was sent on the body on POST /authorize
    }
    tokenBodyParameters: {
        "extra_parameters_assertion": "ASSERTION_VALUE" // This was sent on the POST body to /token
    },
    tokenQueryParamters: {
        "slice": "SLICE_VALUE" // This was sent on the query string on POST /token
    }
}

Exemplo de solicitação v5

// Example of a GET request with extra parameters
const authRequest = {
    scopes: ["SAMPLE_SCOPE"],
    extraQueryParamters: {
        // Will be sent in query string to /authorize and /token
        "dc": "DC_VALUE",
        "slice": "SLICE_VALUE"
    },
    extraParameters: {
        "extra_parameters_assertion": "ASSERTION_VALUE", // Will be sent in query string to /authorize and in body to /token
    },
};

// Example of a POST request with extra parameters
const authRequest = {
    scopes: ["SAMPLE_SCOPE"],
    httpMethod: "POST", // default is "GET" -> Determines method for "/authorize" call. Calls to "/token" are always POST
    extraQueryParamters: {
        // Will be sent in query string to /authorize and /token
        "dc": "DC_VALUE",
        "slice": "SLICE_VALUE"
    },
    extraParameters: {
        extra_parameter_assertion: "assertion_value", // Will be sent in post body to /authorize and /token
    },
};

Suporte à Política de Abertura de Origem Cruzada (COOP)

O MSAL Browser v5 introduz suporte integrado para Cross-Origin-Opener-Policy (COOP), o que aprimora a segurança ao isolar contextos de navegação. Quando o serviço de autenticação (Microsoft Entra ID ou Azure AD B2C) retorna cabeçalhos COOP, os fluxos de autenticação de pop-up tradicional e de iframe silencioso são restritos. O MSAL v5 fornece um mecanismo de ponte de redirecionamento para lidar com a autenticação em ambientes habilitados para COOP.

O que mudou

Quando os cabeçalhos COOP estão presentes na resposta do serviço de autenticação (por exemplo, Cross-Origin-Opener-Policy: same-origin), os fluxos de autenticação de pop-up e de iframe silenciosos tradicionais falham porque a janela de autenticação não pode se comunicar novamente com a janela principal do aplicativo. MSAL v5 soluciona isso ao introduzir um padrão de ponte para redirecionamento.

Todos os fluxos de autenticação (acquireTokenSilent(), , ssoSilent()loginPopup()e loginRedirect()) agora usam a ponte de redirecionamento. A ponte de redirecionamento manipula a resposta de autenticação de forma diferente com base no fluxo:

• Fluxos de pop-up e silenciosos: a ponte de redirecionamento transmite a resposta de autenticação para a janela principal do aplicativo usando a API BroadcastChannel
• Fluxo de redirecionamento: a ponte de redirecionamento navega de volta para a página do aplicativo que iniciou o redirecionamento com a resposta de autenticação na URL

Como funciona

1. Aplicativo principal: seu aplicativo inicia a autenticação usando loginPopup(), ssoSilent()ou loginRedirect()
2. Redirecionamento: MSAL abre um pop-up/iframe/janela para uma página de autoridade
3. Fluxo de autenticação: a página de autoridade conclui o fluxo OAuth e recebe a resposta de autenticação
4. Tratamento de resposta: a página de redirecionamento usa a nova broadcastResponseToMainFrame() função que:
   • Para fluxos de pop-up/silenciosos: transmite a resposta para a janela principal via API BroadcastChannel
   • Para fluxos de redirecionamento: navega para a página de onde a acquireTokenRedirect é iniciada com a resposta de autenticação
5. Aquisição de token: o aplicativo principal recebe a resposta e conclui a aquisição de token

Etapas da migração

1. Configurar a página intermediária de redirecionamento

Crie uma página que chame broadcastResponseToMainFrame() a partir de @azure/msal-browser/redirect-bridge. Esta página não deve NÃO ser servida com cabeçalhos COOP.

A configuração varia de acordo com o sistema de build — consulte o guia Ponte de Redirecionamento — Configuração específica do framework:

Consulte também:Considerações sobre URI de redirecionamento | Erros de interação em andamento em pop-up | MDN: COOP

2. Atualizar a configuração da MSAL

Aponte redirectUri para uma nova página intermediária de redirecionamento:

const msalConfig = {
    auth: {
        clientId: "{your-client-id}",
        authority: "https://login.microsoftonline.com/common",
        redirectUri: "https://{your-app-home-page}/redirect",
    },
};

Alterações de Comportamento que Quebram a Compatibilidade

Tipos de evento e alterações de InteractionStatus

Consolidamos tipos de eventos e InteractionStatus para refletir o que aconteceu em vez da API em que ela aconteceu.

1. SSO_SILENT e ACQUIRE_TOKEN_BY_CODE eventos foram substituídos por eventos ACQUIRE_TOKEN (START/SUCCESS/FAILURE variantes)
2. ACCOUNT_ADDED e ACCOUNT_REMOVED foram substituídos LOGIN_SUCCESS por e LOGOUT_SUCCESS, respectivamente.
3. LOGIN_START e LOGIN_FAILURE foram substituídos ACQUIRE_TOKEN_START por e ACQUIRE_TOKEN_FAILURE, respectivamente.
4. A carga útil de LOGIN_SUCCESS agora é um objeto AccountInfo.
5. Qualquer login bem-sucedido agora emite tanto um evento LOGIN_SUCCESS quanto um evento ACQUIRE_TOKEN_SUCCESS.

LOGIN_SUCCESS migração de tipo de carga

Se o seu retorno de chamada de evento atualmente converte payloads LOGIN_SUCCESS para AuthenticationResult, atualize-o para usar AccountInfo para LOGIN_SUCCESS e reserve AuthenticationResult para ACQUIRE_TOKEN_SUCCESS.

// BEFORE (v4-style assumption)
import {
    EventType,
    AuthenticationResult,
} from "@azure/msal-browser";

pca.addEventCallback((event) => {
    if (event.eventType === EventType.LOGIN_SUCCESS) {
        const result = event.payload as AuthenticationResult;
        setAccount(result.account); // Will silently fail in v5 where payload is AccountInfo, not AuthenticationResult
    }
});

// AFTER (v5-safe handling)
import {
    EventType,
    AuthenticationResult,
    AccountInfo,
} from "@azure/msal-browser";

pca.addEventCallback((event) => {
    if (event.eventType === EventType.LOGIN_SUCCESS) {
        const account = event.payload as AccountInfo;
        setAccount(account);
    }

    if (event.eventType === EventType.ACQUIRE_TOKEN_SUCCESS) {
        const result = event.payload as AuthenticationResult;
        setAccessToken(result.accessToken);
    }
});

Alterações no formato de mensagem de erro

Para reduzir o tamanho do pacote, as mensagens de erro foram movidas para fora do pacote. Quando um erro é gerado, a message propriedade agora retorna um link genérico para a documentação de erro em vez de uma mensagem de erro descritiva:

// BEFORE (v4)
error.message = "Token request cannot be made without authorization code or refresh token.";

// AFTER (v5)
error.message = "See https://aka.ms/msal.js.errors#request_cannot_be_made for details";

A errorCode propriedade permanece inalterada e ainda pode ser usada para identificar o erro específico. Para obter descrições detalhadas de erro, consulte a documentação de erros.

Atualizando o código de tratamento de erros

Se você exibir erros aos usuários, mapeie errorCode para mensagens amigáveis ao usuário em vez de mostrar error.message diretamente:

// BEFORE (v4)
showError(error.message);

// AFTER (v5) — use errorCode for user-facing messages
const userMessages = {
    request_cannot_be_made: "Please sign in again to continue.",
    interaction_required: "Additional verification is needed.",
    consent_required: "Administrator approval is required for this action.",
    login_required: "Your session has expired. Please sign in again.",
    // Add mappings for error codes your application encounters
};
showError(userMessages[error.errorCode] || "An authentication error occurred.");

Se você interpreta erros em lógica condicional, mude da comparação de strings em message para a comparação de errorCode (essa já era a abordagem recomendada na v4):

// BEFORE (v4) — fragile, relied on message text
if (error.message.includes("interaction_required")) {
    await msalInstance.acquireTokenPopup(request);
}

// AFTER (v5) — use errorCode (stable across versions)
if (error.errorCode === "interaction_required") {
    await msalInstance.acquireTokenPopup(request);
}

Se você registrar erros para diagnóstico, inclua ambos errorCode e message (a mensagem agora contém um link direto para a documentação relevante):

// AFTER (v5) — log errorCode for programmatic use, message for the docs link
logger.error(`MSAL Error [${error.errorCode}]: ${error.message}`);
// Output: MSAL Error [request_cannot_be_made]: See https://aka.ms/msal.js.errors#request_cannot_be_made for details

Alterações nos logs do console

Para reduzir o tamanho do pacote, as mensagens de log do console agora são criptografadas. Em vez de ver mensagens de log completas no console do navegador, você verá um valor de hash:

// BEFORE (v4)
[Wed, 15 Jan 2025 10:30:45 GMT] : abc-123 : @azure/msal-browser@4.27.0 : Info - Returning token from cache

// AFTER (v5)
[Wed, 15 Jan 2025 10:30:45 GMT] : abc-123 : @azure/msal-browser@5.0.0 : Info - 7f3a9b2c

A depuração no console do navegador requer uma etapa adicional para decodificar os registros. Para decodificar logs criptografados de volta para mensagens legíveis, use o script de decodificação. Para obter mais informações sobre como usar o script de decodificação, consulte a documentação do script.