Migreringsguide för ADAL till MSAL för Java

Den här artikeln belyser ändringar som du behöver göra för att migrera ett program som använder Azure Active Directory Authentication Library (ADAL) till Microsofts autentiseringsbibliotek (MSAL).

Både Microsoft Authentication Library for Java (MSAL4J) och Azure AD Authentication Library for Java (ADAL4J) används för att autentisera Microsoft Entra entiteter och begära token från Microsoft Entra ID. Hittills har de flesta utvecklare arbetat med Azure AD för utvecklare (v1.0) för att autentisera med olika identiteter, till exempel arbets- och skolkonton, genom att begära token med hjälp av Azure AD Authentication Library (ADAL).

MSAL erbjuder följande fördelar:

• Eftersom den använder nyare Microsofts identitetsplattform kan du autentisera en bredare uppsättning Microsoft identiteter som Microsoft Entra identiteter, Microsoft konton, sociala och lokala konton via Azure AD Business to Consumer (Azure AD B2C) och sociala eller lokala kundkonton via Microsoft Entra External ID.
• Användarna får den bästa upplevelsen för enkel inloggning.
• Ditt program kan aktivera inkrementellt medgivande och stödja nya funktioner, till exempel villkorlig åtkomst.

MSAL för Java är det autentiseringsbibliotek som vi rekommenderar att du använder med Microsofts identitetsplattform. Inga nya funktioner kommer att implementeras på ADAL4J. Alla ansträngningar framöver är inriktade på att förbättra MSAL.

Du kan lära dig mer om MSAL och komma igång med en översikt över Microsofts autentiseringsbibliotek.

Omfång, inte resurser

ADAL4J hämtar token för resurser medan MSAL för Java hämtar token för scope. Många MSAL för Java klasser kräver en omfångsparameter. Den här parametern är en lista över strängar som deklarerar önskade behörigheter och resurser som begärs. Se Microsoft Graphs behörigheter för exempel på behörigheter.

Du kan lägga till omfångssuffixet /.default i resursen för att migrera dina appar från ADAL till MSAL. För resursvärdet https://graph.microsoft.comför är till exempel motsvarande omfångsvärde https://graph.microsoft.com/.default. Om resursen inte finns i URL-formuläret, men ett resurs-ID i formuläret XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, kan du fortfarande använda omfångsvärdet som XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Mer information om de olika typerna av behörighetsomfång finns i artiklarna Behörigheter och samtycke i Microsofts identitetsplattform och Behörighetsomfång för ett webb-API som accepterar v1.0-token.

Kärnklasser

I ADAL4J representerar klassen AuthenticationContext din anslutning till säkerhetstokentjänsten (STS), eller auktoriseringsservern, via en auktoritet. MSAL för Java är dock utformat för klientprogram. Den innehåller två separata klasser: PublicClientApplication och ConfidentialClientApplication för att representera klientprogram. Det senare, ConfidentialClientApplication, representerar ett program som är utformat för att på ett säkert sätt underhålla en hemlighet, till exempel en programidentifierare för en daemonapp.

I följande tabell visas hur ADAL4J-funktioner mappas till den nya MSAL för Java funktioner:

IAccount i stället för IUser

ADAL4J hanterade användare. Även om en användare representerar en enda mänsklig agent eller programvaruagent kan den ha ett eller flera konton i Microsoft identitetssystemet. En användare kan till exempel ha flera Microsoft Entra ID, Azure AD B2C eller Microsoft personliga konton.

MSAL för Java definierar begreppet Konto via IAccount gränssnittet. Detta är en icke bakåtkompatibel ändring jämfört med ADAL4J. Den fångar det faktum att samma användare kan ha flera konton, och kanske även i olika Microsoft Entra kataloger. MSAL för Java ger bättre information i gästscenarier eftersom hemkontoinformation tillhandahålls.

Beständig cachelagring

ADAL4J hade inte stöd för tokencachen. MSAL för Java lägger till en tokencache för att förenkla hanteringen av tokenlivslängder genom att automatiskt uppdatera förfallna token när det är möjligt och förhindra onödiga uppmaningar för användaren att ange autentiseringsuppgifter när det är möjligt.

Gemensam auktoritet

I v1.0, om du använder auktoriteten https://login.microsoftonline.com/common, kan användare logga in med vilket Microsoft Entra-konto som helst (för vilken organisation som helst).

Om du använder auktoriteten https://login.microsoftonline.com/common i v2.0 kan användare logga in med valfri Microsoft Entra-organisation, eller till och med ett personligt Microsoft-konto (MSA). I MSAL för Java, om du vill begränsa inloggningen till valfritt Microsoft Entra-konto, använder du auktoriteten https://login.microsoftonline.com/organizations (vilket är samma beteende som med ADAL4J). Om du vill ange en auktoritet anger du parametern authority i metoden PublicClientApplication.Builder när du instansierar klassen PublicClientApplication.

v1.0- och v2.0-token

V1.0-slutpunkten (används av ADAL) genererar endast v1.0-token.

V2.0-slutpunkten (används av MSAL) kan generera v1.0- och v2.0-token. Med en egenskap för webb-API:ets programmanifest kan utvecklare välja vilken version av token som godkänns. Se accessTokenAcceptedVersion i referensdokumentationen för programmanifestet.

Mer information om v1.0- och v2.0-token finns i Microsoft Entra åtkomsttoken.

Migrering från ADAL till MSAL

I ADAL4J exponerades uppdateringstoken, vilket gjorde det möjligt för utvecklare att cachelagrar dem. De skulle sedan använda AcquireTokenByRefreshToken() för att aktivera lösningar som att implementera långvariga tjänster som uppdaterar instrumentpaneler för användarens räkning när användaren inte längre är ansluten.

MSAL för Java exponerar inte uppdateringstoken av säkerhetsskäl. I stället hanterar MSAL uppdateringstoken åt dig.

MSAL för Java har ett API som gör det möjligt att migrera uppdateringstoken som erhållits med ADAL4J till ClientApplication: RefreshTokenParameters. Med den här metoden kan du ange den tidigare använda uppdateringstoken tillsammans med eventuella omfång (resurser) som du vill. Uppdateringstoken byts ut mot en ny och cachelagras för användning av ditt program.

Följande kodfragment visar ett enkelt kodfragment för migrering i ett konfidentiellt klientprogram:

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

IAuthenticationResult Returnerar en åtkomsttoken och ID-token, medan din nya uppdateringstoken lagras i cacheminnet. Programmet kommer nu också att innehålla en IAccount:

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

Om du vill använda de token som nu finns i cacheminnet anropar du:

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