Guia de migração da ADAL para MSAL para Java

Este artigo destaca as alterações que você precisa fazer para migrar um aplicativo que usa a Biblioteca de Autenticação Azure Active Directory (ADAL) para o Biblioteca do Microsoft Authenticator (MSAL).

Tanto o Biblioteca de Autenticação da Microsoft para Java (MSAL4J) quanto a Biblioteca de Autenticação do Azure AD para Java (ADAL4J) são usados para autenticar entidades do Microsoft Entra e solicitar tokens do Microsoft Entra ID. Até agora, a maioria dos desenvolvedores trabalhou com Azure AD para desenvolvedores (v1.0) para autenticar com várias identidades, como contas corporativas e de estudante, solicitando tokens usando Azure ADAL (Biblioteca de Autenticação do AD).

A MSAL oferece os seguintes benefícios:

• Como ele usa o plataforma de identidade da Microsoft mais recente, você pode autenticar um conjunto mais amplo de identidades Microsoft, como identidades Microsoft Entra, contas Microsoft, contas sociais e locais por meio de Azure AD Business to Consumer (Azure AD B2C) e contas de clientes sociais ou locais por meio de ID externa do Microsoft Entra.
• Os usuários terão a melhor experiência de logon único.
• Seu aplicativo pode habilitar o consentimento incremental, bem como dar suporte a novos recursos, como acesso condicional.

A MSAL para Java é a biblioteca de autenticação que recomendamos que você use com o plataforma de identidade da Microsoft. Nenhum novo recurso será implementado na ADAL4J. Todos os esforços daqui para frente estão focados em melhorar a MSAL.

Você pode saber mais sobre a MSAL e começar a ter uma visão geral do Biblioteca do Microsoft Authenticator.

Escopos não são recursos

A ADAL4J adquire tokens para recursos, enquanto a MSAL para Java adquire tokens para escopos. Muitas classes do MSAL for Java exigem um parâmetro de escopo. Esse parâmetro é uma lista de cadeias de caracteres que declaram as permissões e os recursos desejados solicitados. Consulte os escopos do Microsoft Graph para ver exemplos de escopos.

Você pode adicionar o /.default sufixo de escopo ao recurso para ajudar a migrar seus aplicativos da ADAL para a MSAL. Por exemplo, para o valor do recurso https://graph.microsoft.com, o valor de escopo equivalente é https://graph.microsoft.com/.default. Se o recurso não estiver no formulário de URL, mas uma ID de recurso do formulário XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, você ainda poderá usar o valor de escopo como XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Para obter mais detalhes sobre os diferentes tipos de escopos, consulte os artigos Permissões e consentimento na plataforma de identidade da Microsoft e Escopos para uma API Web que aceita tokens v1.0.

Classes principais

No ADAL4J, a AuthenticationContext classe representa sua conexão com o STS (Serviço de Token de Segurança) ou o servidor de autorização, por meio de uma Autoridade. No entanto, a MSAL para Java foi projetada em torno de aplicativos cliente. Ele fornece duas classes separadas: PublicClientApplication e ConfidentialClientApplication para representar aplicativos cliente. Este último representa ConfidentialClientApplicationum aplicativo projetado para manter com segurança um segredo, como um identificador de aplicativo para um aplicativo daemon.

A tabela a seguir mostra como as funções ADAL4J são mapeadas para a nova MSAL para funções de Java:

IAccount em vez de IUser

ADAL4J gerenciava usuários. Embora um usuário represente um único agente humano ou de software, ele pode ter uma ou mais contas no sistema de identidade Microsoft. Por exemplo, um usuário pode ter várias contas pessoais Microsoft Entra ID, Azure AD B2C ou Microsoft.

A MSAL para Java define o conceito de Conta por meio da IAccount interface. Essa é uma alteração significativa da ADAL4J. Ele captura o fato de que o mesmo usuário pode ter várias contas e, talvez, até mesmo em diretórios de Microsoft Entra diferentes. A MSAL para Java fornece informações melhores em cenários de convidado porque as informações da conta inicial são fornecidas.

Persistência de cache

A ADAL4J não tinha suporte para cache de token. A MSAL para Java adiciona um cache de token para simplificar o gerenciamento de tempos de vida do token atualizando automaticamente tokens expirados quando possível e impedindo solicitações desnecessárias para que o usuário forneça credenciais quando possível.

Autoridade Comum

Na v1.0, se você usar a https://login.microsoftonline.com/common autoridade, os usuários poderão entrar com qualquer conta Microsoft Entra (para qualquer organização).

Se você usar a autoridade https://login.microsoftonline.com/common na versão 2.0, os usuários poderão entrar usando qualquer organização do Microsoft Entra ou até mesmo uma conta pessoal da Microsoft (MSA). No MSAL para Java, se você quiser restringir o login a contas do Microsoft Entra, use a autoridade https://login.microsoftonline.com/organizations (que é o mesmo comportamento da ADAL4J). Para especificar uma autoridade, defina o authority parâmetro no PublicClientApplication.Builder método ao instanciar uma PublicClientApplication classe.

Tokens v1.0 e v2.0

O ponto de extremidade v1.0 (usado pela ADAL) emite apenas tokens v1.0.

O endpoint v2.0 (usado pela MSAL) pode emitir tokens v1.0 e v2.0. Uma propriedade do manifesto do aplicativo da API Web permite que os desenvolvedores escolham qual versão do token é aceita. Consulte accessTokenAcceptedVersion na documentação de referência do manifesto de aplicativo.

Para obter mais informações sobre tokens v1.0 e v2.0, consulte Microsoft Entra tokens de acesso.

Migração da ADAL para MSAL

No ADAL4J, os tokens de atualização foram expostos, o que permitiu que os desenvolvedores os armazenassem em cache. Em seguida, eles usariam AcquireTokenByRefreshToken() para habilitar soluções como implementar serviços de execução longa que atualizam painéis em nome do usuário quando o usuário não estiver mais conectado.

A MSAL para Java não expõe tokens de atualização por motivos de segurança. Em vez disso, a MSAL atualiza os tokens para você.

O MSAL para Java tem uma API que permite migrar tokens de atualização obtidos com o ADAL4J para o ClientApplication: RefreshTokenParameters. Com esse método, você pode fornecer o token de atualização usado anteriormente junto com todos os escopos (recursos) desejados. O token de atualização será trocado por um novo e armazenado em cache para uso pelo aplicativo.

O trecho de código a seguir mostra um código de migração simples em um aplicativo cliente confidencial:

String rt = GetCachedRefreshTokenForSignedInUser(); // Get refresh token from where you have them stored
Set<String> scopes = Collections.singleton("SCOPE_FOR_REFRESH_TOKEN");

RefreshTokenParameters parameters = RefreshTokenParameters.builder(scopes, rt).build();

PublicClientApplication app = PublicClientApplication.builder(CLIENT_ID) // ClientId for your application
                .authority(AUTHORITY)  //plug in your authority
                .build();

IAuthenticationResult result = app.acquireToken(parameters);

O IAuthenticationResult retorna um token de acesso e um token de ID, enquanto seu novo token de atualização é armazenado no cache. O aplicativo também agora conterá um IAccount:

Set<IAccount> accounts =  app.getAccounts().join();

Para usar os tokens que estão agora no cache, chame:

SilentParameters parameters = SilentParameters.builder(scope, accounts.iterator().next()).build();
IAuthenticationResult result = app.acquireToken(parameters);