Migratiehandleiding voor ADAL naar MSAL voor Java

  • Artikel
  • 5 minuten om te lezen

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 msal (Microsoft Authentication Library) te gebruiken.

Zowel de Microsoft Authentication Library voor Java (MSAL4J) als Azure AD Authentication Library for Java (ADAL4J) worden gebruikt voor het verifiëren van Azure AD entiteiten en het aanvragen van tokens van Azure AD. Tot nu toe werkten de meeste ontwikkelaars met Azure AD voor ontwikkelaarsplatform (v1.0) 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 B2C (Business to Consumer).
  • Uw gebruikers krijgen de beste ervaring met eenmalige aanmelding.
  • Uw toepassing kan incrementele toestemming inschakelen en het ondersteunen van voorwaardelijke toegang is eenvoudiger.

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

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

Bereiken, niet resources

ADAL4J verkrijgt tokens voor resources, terwijl MSAL voor Java tokens voor bereiken verkrijgt. Veel MSAL voor Java-klassen vereisen een bereikparameter. Deze parameter is een lijst met tekenreeksen die de gewenste machtigingen en resources declareren die worden aangevraagd. Zie De bereiken van Microsoft Graph om voorbeeldbereiken te bekijken.

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.comis de equivalente bereikwaarde https://graph.microsoft.com/.default. Als de resource zich niet in het URL-formulier bevindt, maar een resource-id van het formulier XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, kunt u de bereikwaarde nog steeds gebruiken als XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Raadpleeg machtigingen en toestemming in de Microsoft identity platform en de bereiken voor een web-API die artikelen over v1.0-tokens accepteert voor meer informatie over de verschillende typen bereiken.

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 om clienttoepassingen te vertegenwoordigen. De laatste, ConfidentialClientApplication, vertegenwoordigt een toepassing die is ontworpen voor het veilig onderhouden van een geheim, zoals een toepassings-id voor een daemon-app.

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

Methode ADAL4J METHODE MSAL4J
acquireToken(Tekenreeksresource, ClientCredential-referentie, AuthenticationCallback-callback) acquireToken(ClientCredentialParameters)
acquireToken(Tekenreeksresource, ClientAssertion-assertie, AuthenticationCallback-callback) acquireToken(ClientCredentialParameters)
acquireToken(Tekenreeksresource, AsymmetricKeyCredential-referentie, AuthenticationCallback-callback) acquireToken(ClientCredentialParameters)
acquireToken(String resource, String clientId, String username, String password, AuthenticationCallback callback) acquireToken(UsernamePasswordParameters)
acquireToken(String resource, String clientId, String username, String password=null, AuthenticationCallback callback) acquireToken(IntegratedWindowsAuthenticationParameters)
acquireToken(String resource, UserAssertion userAssertion, ClientCredential credential, AuthenticationCallback callback) acquireToken(OnBehalfOfParameters)
acquireTokenByAuthorizationCode() acquireToken(AuthorizationCodeParameters)
acquireDeviceCode() en acquireTokenByDeviceCode() acquireToken(DeviceCodeParameters)
acquireTokenByRefreshToken() acquireTokenSilently(SilentParameters)

IAccount in plaats van IUser

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

MSAL voor Java definieert het concept account via de IAccount interface. Dit is een belangrijke wijziging ten aanzien van ADAL4J, maar het is een goede wijziging omdat het vastlegt dat dezelfde gebruiker meerdere accounts kan hebben, en misschien zelfs in verschillende Azure AD directory's. MSAL voor Java biedt betere informatie in gastscenario's omdat er informatie over het thuisaccount wordt verstrekt.

Cachepersistentie

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 indien mogelijk automatisch te vernieuwen en onnodige prompts voor de gebruiker om referenties op te geven, indien mogelijk, te voorkomen.

Gemeenschappelijke autoriteit

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

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

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 de referentiedocumentatie voor het toepassingsmanifest .

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

Migratie van ADAL naar MSAL

In ADAL4J werden de vernieuwingstokens weergegeven, waardoor ontwikkelaars deze in de cache konden opslaan. Ze gebruiken AcquireTokenByRefreshToken() vervolgens om oplossingen in te schakelen, zoals het implementeren van langlopende services die dashboards vernieuwen namens de gebruiker wanneer de gebruiker niet meer verbonden is.

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

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

In het volgende codefragment ziet u 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 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);