Migratiehandleiding voor ADAL naar MSAL voor Java

In dit artikel worden de wijzigingen beschreven die u moet aanbrengen om een toepassing te migreren die gebruikmaakt van de Azure Active Directory Authentication Library (ADAL) naar de Microsoft Authentication Library (MSAL).

Zowel de Microsoft Authentication Library voor Java (MSAL4J) als Azure AD Authentication Library voor Java (ADAL4J) worden gebruikt om Microsoft Entra entiteiten en aanvraagtokens van Microsoft Entra ID te verifiëren. Tot nu toe hebben de meeste ontwikkelaars met Azure AD gewerkt voor ontwikkelaars (v1.0) voor verificatie met verschillende identiteiten, zoals werk- en schoolaccounts, door tokens aan te vragen met behulp van Azure AD Authentication Library (ADAL).

MSAL biedt de volgende voordelen:

• Omdat deze gebruikmaakt van de nieuwere Microsoft identity platform, kunt u een bredere set Microsoft identiteiten verifiëren, zoals Microsoft Entra identiteiten, Microsoft accounts, sociale en lokale accounts via Azure AD Business to Consumer (Azure AD B2C) en sociale of lokale klantaccounts via Microsoft Entra Externe id.
• Uw gebruikers krijgen de beste single-sign-on-ervaring.
• Uw toepassing kan incrementele toestemming inschakelen en nieuwe functies ondersteunen, zoals voorwaardelijke toegang.

MSAL for Java is de authenticatiebibliotheek die we u aanraden te gebruiken met het Microsoft-identiteitsplatform. Er worden geen nieuwe functies geïmplementeerd op ADAL4J. Alle inspanningen in de toekomst zijn gericht op het verbeteren van MSAL.

U kunt meer informatie over MSAL vinden en aan de slag gaan met een overzicht van de Microsoft Authentication Library.

Machtigingen, geen resources

ADAL4J haalt tokens op voor resources, terwijl MSAL voor Java tokens voor machtigingen ophaalt. Voor veel MSAL-klassen voor Java is een bereikparameter vereist. Deze parameter is een lijst met tekenreeksen die de gewenste machtigingen en resources declareren die worden aangevraagd. Zie de scopes van Microsoft Graph voor voorbeeldscopes.

U kunt het /.default bereikachtervoegsel toevoegen aan de resource om uw apps te migreren van de ADAL naar MSAL. Bijvoorbeeld, voor de resourcewaarde van https://graph.microsoft.com is de equivalente scopewaarde https://graph.microsoft.com/.default. Als de resource niet de URL-indeling heeft, maar een resource-id in de vorm van XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, kunt u de scopewaarde nog steeds gebruiken als XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Raadpleeg Machtigingen en toestemming in het Microsoft Identity Platform en het artikel Scopes voor een web-API die v1.0-tokens accepteert voor meer details over de verschillende typen scopes.

Kernklassen

In ADAL4J vertegenwoordigt de AuthenticationContext klasse uw verbinding met de Security Token Service (STS) of autorisatieserver via een instantie. MSAL voor Java is echter ontworpen rond clienttoepassingen. Het biedt twee afzonderlijke klassen: PublicClientApplication en ConfidentialClientApplication vertegenwoordigt clienttoepassingen. Deze laatste vertegenwoordigt ConfidentialClientApplicationeen toepassing die is ontworpen om een geheim zoals een toepassings-id voor een daemon-app veilig te onderhouden.

In de volgende tabel ziet u hoe ADAL4J-functies worden toegewezen aan de nieuwe MSAL voor Java-functies:

Methode ADAL4J	MSAL4J-methode
acquireToken(string resource, ClientCredential credential, AuthenticationCallback callback)	ClientCredentialParameters
acquireToken(Tekenreeksresource, ClientAssertion-assertie, AuthenticationCallback callback)	ClientCredentialParameters
acquireToken(string resource, AsymmetricKeyCredential credential, AuthenticationCallback callback)	ClientCredentialParameters
acquireToken(String resource, String clientId, String username, String password, AuthenticationCallback callback)	UserNamePasswordParameters
acquireToken(String resource, String clientId, String username, String password=null, AuthenticationCallback callback)	IntegratedWindowsAuthenticationParameters
acquireToken(string resource, UserAssertion userAssertion, ClientCredential credential, AuthenticationCallback callback)	OnBehalfOfParameters
acquireTokenByAuthorizationCode()	AuthorizationCodeParameters
acquireDeviceCode() en acquireTokenByDeviceCode()	DeviceCodeFlowParameters
acquireTokenByRefreshToken()	SilentParameters

IAccount in plaats van IUser

ADAL4J verwerkt gebruikers. Hoewel een gebruiker één menselijke of softwareagent vertegenwoordigt, kan deze een of meer accounts hebben in het Microsoft identiteitssysteem. Een gebruiker kan bijvoorbeeld meerdere Microsoft Entra ID, Azure AD B2C of Microsoft persoonlijke accounts hebben.

MSAL voor Java definieert het concept account via de IAccount interface. Dit is een belangrijke wijziging van ADAL4J. Het legt vast dat dezelfde gebruiker meerdere accounts kan hebben, en misschien zelfs in verschillende Microsoft Entra mappen. MSAL voor Java biedt betere informatie in gastscenario's omdat informatie over het thuisaccount wordt verstrekt.

Cachepersistentie

ADAL4J had geen ondersteuning voor tokencache. MSAL voor Java voegt een tokencache toe om de levensduur van tokens te vereenvoudigen door verlopen tokens automatisch te vernieuwen indien mogelijk en onnodige prompts te voorkomen dat de gebruiker waar mogelijk referenties opgeeft.

Gemeenschappelijke instantie

Als u de https://login.microsoftonline.com/common instantie gebruikt in v1.0, kunnen gebruikers zich aanmelden met een Microsoft Entra-account (voor elke organisatie).

Als u de https://login.microsoftonline.com/common autoriteit in v2.0 gebruikt, kunnen gebruikers zich aanmelden met een willekeurige Microsoft Entra-organisatie, of zelfs met een persoonlijk Microsoft-account (MSA). Als u in MSAL voor Java het aanmelden wilt beperken tot een willekeurig Microsoft Entra-account, gebruikt u de https://login.microsoftonline.com/organizations authority (dit is hetzelfde gedrag als in ADAL4J). Als u een instantie wilt opgeven, stelt u de authority parameter in de PublicClientApplication.Builder methode in wanneer u een PublicClientApplication klasse instantieert.

v1.0- en v2.0-tokens

Het v1.0-eindpunt (gebruikt door ADAL) verzendt alleen v1.0-tokens.

Het v2.0-eindpunt (gebruikt door MSAL) kan v1.0- en v2.0-tokens verzenden. Met een eigenschap van het toepassingsmanifest van de web-API kunnen ontwikkelaars kiezen welke versie van het token wordt geaccepteerd. Zie accessTokenAcceptedVersion in de referentiedocumentatie voor het toepassingsmanifest.

Zie Microsoft Entra toegangstokens voor meer informatie over v1.0- en v2.0-tokens.

Migratie van ADAL naar MSAL

In ADAL4J werden de vernieuwingstokens weergegeven, waardoor ontwikkelaars ze in de cache konden opslaan. Ze zouden vervolgens AcquireTokenByRefreshToken() gebruiken om oplossingen mogelijk te maken, zoals het implementeren van services die langdurig actief blijven en dashboards namens de gebruiker vernieuwen wanneer de gebruiker niet langer verbonden is.

MSAL voor Java stelt om veiligheidsredenen geen refreshtokens beschikbaar. In plaats daarvan verwerkt MSAL het vernieuwen van tokens voor u.

MSAL voor Java heeft een API waarmee u vernieuwingstokens die met ADAL4J zijn verkregen, kunt migreren naar : ClientApplicationRefreshTokenParameters. Met deze methode kunt u de eerder gebruikte refresh-token opgeven, samen met alle gewenste scopes (resources). Het vernieuwingstoken wordt uitgewisseld voor een nieuw token en in de cache opgeslagen voor gebruik door uw toepassing.

In het volgende codefragment ziet u een eenvoudig codefragment voor migratie in een vertrouwelijke clienttoepassing:

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);

Het IAuthenticationResult retourneert een toegangstoken en id-token, terwijl uw nieuwe vernieuwingstoken wordt opgeslagen in de cache. De toepassing bevat nu ook een IAccount:

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

Als u de tokens wilt gebruiken die zich nu in de cache bevinden, roept u het volgende aan:

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