Migratiehandleiding voor ADAL naar MSAL voor Java

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

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

MSAL biedt de volgende voordelen:

• Omdat de nieuwere Microsoft identity platform wordt gebruikt, kunt u een bredere set Microsoft-identiteiten verifiëren, zoals Azure AD-identiteiten, Microsoft-accounts en sociale en lokale accounts via Azure AD Business to Consumer (B2C).
• Uw gebruikers krijgen de beste ervaring voor een een-op-een-aanmelding.
• Uw toepassing kan incrementele toestemming inschakelen en het ondersteunen van voorwaardelijke toegang is eenvoudiger.

MSAL voor Java is de auth-bibliotheek die u het beste kunt gebruiken met de Microsoft identity platform. Er worden geen nieuwe functies geïmplementeerd op ADAL4J. Alle inspanningen die in de toekomst worden gedaan, zijn gericht op het verbeteren van MSAL.

Meer informatie over MSAL en aan de slag met een overzicht van de Microsoft Authentication Library.

Verschillen

Als u hebt gewerkt met het Azure AD-eindpunt voor ontwikkelaars (v1.0) (en ADAL4J), wilt u wellicht Wat is er anders aan de Microsoft identity platform?.

Scopes, geen resources

ADAL4J verkrijgt tokens voor resources, terwijl MSAL voor Java tokens voor scopes verkrijgt. Voor een aantal MSAL-klassen voor Java-klassen is een scopes-parameter vereist. Deze parameter is een lijst met tekenreeksen die de gewenste machtigingen en resources declareeren die worden aangevraagd. Zie Microsoft Graph-scopes voor voorbeeldbereiken.

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

Zie de artikelen Machtigingen en toestemming in de Microsoft identity platform en De scopes voor een web-API die v1.0-tokens accepteert voor meer informatie over de verschillende typen scopes.

Kernklassen

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

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

IAccount in plaats van IUser

ADAL4J heeft gebruikers gemanipuleerd. Hoewel een gebruiker één persoon of softwareagent vertegenwoordigt, kan deze een of meer accounts in het Microsoft-identiteitssysteem hebben. Een gebruiker kan bijvoorbeeld verschillende persoonlijke Azure AD-, Azure AD B2C- of Microsoft-accounts hebben.

MSAL voor Java definieert het concept account via de IAccount interface. Dit is een wijziging die de ADAL4J verbreekt, maar het is een goede wijziging omdat deze het feit legt dat dezelfde gebruiker meerdere accounts kan hebben, en misschien zelfs in verschillende Azure AD-directories. MSAL voor Java biedt betere informatie in gastscenario's omdat de gegevens van het thuisaccount worden verstrekt.

Cache-persistentie

ADAL4J heeft geen ondersteuning voor tokencache. MSAL voor Java voegt een tokencache toe om het beheer van de levensduur van tokens te vereenvoudigen door verlopen tokens automatisch te vernieuwen wanneer dit mogelijk is en onnodige prompts voor de gebruiker te voorkomen om waar mogelijk referenties op te geven.

Algemene instantie

Als u in v1.0 de instantie gebruikt, kunnen gebruikers zich aanmelden met elk https://login.microsoftonline.com/common Azure Active Directory -account (AAD) (voor elke organisatie).

Als u de instantie in v2.0 gebruikt, kunnen gebruikers zich aanmelden met elke AAD organisatie of zelfs met een persoonlijk https://login.microsoftonline.com/common Microsoft-account (MSA). Als u in MSAL voor Java aanmelding wilt beperken tot een AAD-account, gebruikt u de instantie (hetzelfde gedrag als https://login.microsoftonline.com/organizations bij ADAL4J). Als u een instantie wilt opgeven, stelt u authority de parameter in de methode PublicClientApplication.Builder in wanneer u uw klasse PublicClientApplication maakt.

v1.0- en v2.0-tokens

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

Het v2.0-eindpunt (gebruikt door MSAL) kan v1.0- en v2.0-tokens genereren. Een eigenschap van het toepassingsmanifest van de web-API stelt ontwikkelaars in staat om te kiezen welke versie van het token wordt geaccepteerd. Zie accessTokenAcceptedVersion de referentiedocumentatie voor het toepassingsmanifest.

Zie toegangstokens voor meer informatie over v1.0- Azure Active Directory v2.0-tokens.

Migratie van ADAL naar MSAL

In ADAL4J werden de vernieuwingstokens zichtbaar, waardoor ontwikkelaars ze in de cache konden cachen. Vervolgens wordt gebruikt om oplossingen in te stellen, zoals het implementeren van langlopende services waarmee dashboards namens de gebruiker worden vernieuwd wanneer de gebruiker AcquireTokenByRefreshToken() niet meer verbonden is.

MSAL voor Java geeft geen vernieuwingstokens weer uit veiligheidsoverwegingen. In plaats daarvan verwerkt MSAL het vernieuwen van tokens voor u.

MSAL voor Java heeft een API waarmee u vernieuwingstokens die u met ADAL4j hebt verkregen, kunt migreren naar ClientApplication: acquireToken(RefreshTokenParameters). Met deze methode kunt u het eerder gebruikte vernieuwings token samen met de wenste scopes (resources) leveren. Het vernieuwings token wordt uitgewisseld voor een nieuw token en in de cache opgeslagen voor gebruik door uw toepassing.

Het volgende codefragment toont een deel van de migratiecode 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);

De IAuthenticationResult retourneert een toegangtoken en id-token, terwijl het nieuwe vernieuwingtoken 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 nu in de cache staan, roept u het volgende aan:

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