Migreringsguide för ADAL till MSAL för Java

Den här artikeln visar de ändringar du behöver göra för att migrera en app som använder Azure Active Directory Authentication Library (ADAL) för att använda Microsoft Authentication Library (MSAL).

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

MSAL har följande fördelar:

• Eftersom den använder den nyare Microsofts identitetsplattform kan du autentisera en bredare uppsättning Microsoft-identiteter som Azure AD-identiteter, Microsoft-konton och sociala och lokala konton via Azure AD Business to Consumer (B2C).
• Användarna får den bästa upplevelsen för enkel inloggning.
• Ditt program kan aktivera inkrementellt medgivande och det är enklare att ge stöd för 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. Allt arbete framöver fokuserar på att förbättra MSAL.

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

Skillnader

Om du har arbetat med slutpunkten Azure AD för utvecklare (v1.0) (och ADAL4J) kanske du vill läsa Vad är annorlunda med Microsofts identitetsplattform?.

Omfång, inte resurser

ADAL4J hämtar token för resurser medan MSAL för Java hämtar token för omfång. Ett antal MSAL för Java-klasser kräver en scopes-parameter. Den här parametern är en lista över strängar som deklarerar önskade behörigheter och resurser som begärs. Se Microsoft Graph omfång för att se exempelomfång.

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

Mer information om de olika typerna av omfång finns i artiklarna Behörigheter och medgivande i Microsofts identitetsplattform och Omfång för ett webb-API som accepterar v1.0-tokens.

Kärnklasser

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

Följande tabell visar hur ADAL4J-funktioner mappar till de nya MSAL för Java-funktionerna:

IAccount i stället för IUser

ADAL4J manipulerade användare. Även om en användare representerar en enskild mänsklig agent eller programvaruagent kan den ha ett eller flera konton i Microsofts identitetssystem. En användare kan till exempel ha flera personliga Azure AD-, Azure AD B2C- eller Microsoft-konton.

MSAL för Java definierar begreppet Konto via IAccount gränssnittet. Det här är en stor förändring från ADAL4J, men den är bra eftersom den visar det faktum att samma användare kan ha flera konton och kanske till och med i olika Azure AD-kataloger. MSAL för Java ger bättre information i gästscenarier eftersom hemkontoinformation tillhandahålls.

Cachepersistence

ADAL4J hade inte stöd för tokencache. MSAL för Java lägger till en tokencache för att förenkla hanteringen av tokenlivslängd genom att automatiskt uppdatera utgångna 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

Om du använder behörigheten i v1.0 kan användarna logga in med val Azure Active Directory https://login.microsoftonline.com/common -konton (AAD) (för alla organisationer).

Om du använder auktoriteten i v2.0 kan användarna logga in med valfri AAD organisation eller till och med ett https://login.microsoftonline.com/common personligt Microsoft-konto (MSA). Om du vill begränsa inloggningen till ett AAD-konto i MSAL för Java använder du behörigheten (vilket är samma beteende som https://login.microsoftonline.com/organizations med ADAL4J). Ange en auktoritet genom att ange authority parametern i metoden PublicClientApplication.Builder när du skapar PublicClientApplication klassen.

v1.0- och v2.0-token

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

V2.0-slutpunkten (som används av MSAL) kan generera v1.0- och v2.0-token. En egenskap för programmanifestet för webb-API:et gör det möjligt för utvecklare att välja vilken version av token som accepteras. Se accessTokenAcceptedVersion i referensdokumentationen för programmanifestet.

Mer information om v1.0- och v2.0-token finns i Azure Active Directory åtkomsttoken.

Migrering från ADAL till MSAL

I ADAL4J exponerades uppdateringstoken, vilket gjorde det möjligt för utvecklare att cachelagra dem. De skulle sedan använda för att aktivera lösningar som att implementera långvariga tjänster som uppdaterar instrumentpaneler för användarens räkning AcquireTokenByRefreshToken() 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 att du kan migrera uppdateringstoken som du har införskaffade med ADAL4j till ClientApplication: acquireToken(RefreshTokenParameters). Med den här metoden kan du ange den tidigare använda uppdateringstoken tillsammans med de omfång (resurser) som du önskar. Uppdateringstoken kommer att utbytas mot en ny och cachelagras för användning av ditt program.

Följande kodfragment visar viss migreringskod 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);

returnerar IAuthenticationResult en åtkomsttoken och ID-token medan din nya uppdateringstoken lagras i cacheminnet. Programmet kommer nu också att innehålla ett 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);