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

Este artigo destaca as alterações que precisa de fazer para migrar uma aplicação que utiliza a Azure Active Directory Authentication Library (ADAL) para a Biblioteca de Autenticação da Microsoft (MSAL).

Tanto a biblioteca Biblioteca de Autenticação da Microsoft para Java (MSAL4J) como a biblioteca Azure AD Authentication Library for Java (ADAL4J) são utilizadas para autenticar entidades do Microsoft Entra e solicitar tokens do Microsoft Entra ID. Até agora, a maioria dos programadores tem trabalhado com o Azure AD for developers (v1.0) para autenticar com várias identidades, como contas de trabalho e escola, solicitando tokens usando a Biblioteca de Autenticação do Azure AD (ADAL).

A MSAL oferece os seguintes benefícios:

• Como utiliza a mais recente plataforma de identidades da Microsoft, pode autenticar um conjunto mais amplo de identidades da Microsoft, como identidades Microsoft Entra, contas Microsoft, contas sociais e locais através do Azure AD Business to Consumer (Azure AD B2C), e contas de clientes sociais ou locais através do ID externo Microsoft Entra.
• Os seus utilizadores terão a melhor experiência de login único.
• A sua aplicação pode permitir consentimento incremental, bem como suportar novas funcionalidades, como o Acesso Condicional.

MSAL para Java é a biblioteca de autenticação que recomendamos que utilize com a plataforma de identidades da Microsoft. Não serão implementadas novas funcionalidades no ADAL4J. Todos os esforços daqui para a frente estão focados na melhoria do MSAL.

Pode saber mais sobre a MSAL e começar com uma visão geral da Biblioteca de Autenticação da Microsoft.

Escopos, não recursos

O ADAL4J adquire tokens para recursos, enquanto o MSAL para Java adquire tokens para escopos. Muitas classes do MSAL para Java exigem um parâmetro de âmbitos. Este parâmetro é uma lista de strings que declaram as permissões e recursos desejados que são solicitados. Consulte os telescópios do Microsoft Graph para ver exemplos de telescópios.

Pode adicionar o sufixo /.default de âmbito ao recurso para ajudar a migrar as suas aplicações do ADAL para o MSAL. Por exemplo, para o valor de recurso de https://graph.microsoft.com, o valor equivalente do âmbito é https://graph.microsoft.com/.default. Se o recurso não estiver no formulário URL, mas sim num ID de recurso do formulário XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, pode ainda usar o valor do âmbito como XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

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

Disciplinas obrigatórias

No ADAL4J, a AuthenticationContext classe representa a sua ligação ao Security Token Service (STS), ou servidor de autorização, através de uma Autoridade. No entanto, o MSAL para Java é concebido em torno de aplicações cliente. Fornece duas classes separadas: PublicClientApplication e ConfidentialClientApplication para representar aplicações cliente. Este último, ConfidentialClientApplication, representa uma aplicação concebida para manter de forma segura um segredo, como um identificador de aplicação para uma aplicação daemon.

A tabela seguinte mostra como as funções ADAL4J correspondem ao novo MSAL para funções Java:

IAccount em vez de IUser

ADAL4J geria utilizadores. Embora um utilizador represente um único humano ou agente de software, pode ter uma ou mais contas no sistema de identidade da Microsoft. Por exemplo, um utilizador pode ter várias contas pessoais do Microsoft Entra ID, Azure AD B2C ou Microsoft.

O MSAL para Java define o conceito de Conta através da IAccount interface. Isto é uma mudança total em relação ao ADAL4J. Capta o facto de que o mesmo utilizador pode ter várias contas, e talvez até em diferentes diretórios da Microsoft Entra. O MSAL para Java fornece informações mais detalhadas em cenários com utilizadores convidados, porque são fornecidas informações da conta principal.

Persistência da cache

O ADAL4J não tinha suporte para cache de tokens. O MSAL para Java adiciona uma cache de tokens para simplificar a gestão da vida útil dos tokens, atualizando automaticamente os tokens expirados sempre que possível e evitando pedidos desnecessários para que o utilizador forneça credenciais sempre que possível.

Autoridade Comum

Na versão 1.0, se usar a https://login.microsoftonline.com/common autoridade, os utilizadores podem iniciar sessão com qualquer conta Microsoft Entra (para qualquer organização).

Se usar a autoridade https://login.microsoftonline.com/common na versão 2.0, os utilizadores podem iniciar sessão com qualquer organização Microsoft Entra, ou mesmo com uma conta pessoal da Microsoft (MSA). No MSAL para Java, se quiseres restringir o login a qualquer conta Microsoft Entra, usa a https://login.microsoftonline.com/organizations autoridade (que é o mesmo comportamento do ADAL4J). Para especificar uma autoridade, define o authority parâmetro no PublicClientApplication.Builder método quando instancias uma PublicClientApplication classe.

Tokens v1.0 e v2.0

O endpoint v1.0 (usado pela ADAL) apenas emite tokens v1.0.

O endpoint v2.0 (usado pela MSAL) pode emitir tokens v1.0 e v2.0. Uma propriedade do manifesto da aplicação da API web permite aos programadores escolher qual a versão do token aceite. Consulte accessTokenAcceptedVersion a documentação de referência sobre o manifesto da aplicação.

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

Migração de ADAL para MSAL

No ADAL4J, os tokens de atualização estavam expostos — o que permitia aos programadores armazená-los em cache. Depois, usariam AcquireTokenByRefreshToken() para habilitar soluções como a implementação de serviços de longa duração que atualizam os painéis de controlo em nome do utilizador quando este já não está ligado.

O MSAL para Java não expõe tokens de atualização por razões de segurança. Em vez disso, a MSAL lida com tokens de atualização para você.

O MSAL para Java tem uma API que permite migrar tokens de atualização adquiridos com o ADAL4J para o ClientApplication: RefreshTokenParameters. Com este método, pode fornecer o token de atualização usado anteriormente juntamente com quaisquer escopos (recursos) que desejar. O token de atualização será trocado por um novo e armazenado em cache para uso pela sua aplicação.

O seguinte excerto de código mostra um excerto simples de código de migração numa aplicação 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 o novo token de atualização é armazenado na cache. A aplicação conterá agora também um IAccount:

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

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

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