Migrationsleitfaden für die Migration von ADAL zu MSAL für Java

In diesem Artikel werden Änderungen erläutert, die Sie vornehmen müssen, um eine Anwendung zu migrieren, die die Azure Active Directory-Authentifizierungsbibliothek (ADAL) zum Microsoft Authentication Library (MSAL) (MSAL) verwendet.

Sowohl die Microsoft-Authentifizierungsbibliothek für Java (MSAL4J) als auch Azure AD-Authentifizierungsbibliothek für Java (ADAL4J) werden verwendet, um Microsoft Entra Entitäten zu authentifizieren und Token von Microsoft Entra ID anzufordern. Bisher haben die meisten Entwickler mit Azure AD für Entwickler (v1.0) gearbeitet, um sich mit verschiedenen Identitäten wie Geschäfts-, Schul- und Unikonten zu authentifizieren, indem sie Token mithilfe Azure AD-Authentifizierungsbibliothek (AD Authentication Library, ADAL) anfordern.

MSAL bietet die folgenden Vorteile:

• Da die neuere Microsoft Identity Platform verwendet wird, können Sie eine breitere Gruppe von Microsoft Identitäten wie Microsoft Entra Identitäten, Microsoft Konten, sozialen und lokalen Konten über Azure AD Business to Consumer authentifizieren (Azure AD B2C) und soziale oder lokale Kundenkonten über Microsoft Entra External ID.
• Ihre Benutzer erhalten das beste Single-Sign-On-Erlebnis.
• Ihre Anwendung kann die inkrementelle Zustimmung aktivieren und neue Features wie bedingten Zugriff unterstützen.

MSAL für Java ist die Authentifizierungsbibliothek, die Wir empfehlen, mit dem Microsoft Identity Platform zu verwenden. Auf ADAL4J werden keine neuen Features implementiert. Alle künftigen Anstrengungen konzentrieren sich auf die Verbesserung von MSAL.

Sie können mehr über MSAL erfahren und mit einem Überblick über die Microsoft Authentication Library (MSAL) beginnen.

Bereiche, keine Ressourcen

ADAL4J erwirbt Token für Ressourcen, während MSAL für Java Token für Bereiche erwirbt. Viele MSAL für Java Klassen erfordern einen Bereichsparameter. Dieser Parameter ist eine Liste von Zeichenfolgen, die die gewünschten Berechtigungen und Ressourcen deklarieren, die angefordert werden. Beispiele für Microsoft Graph-Berechtigungen finden Sie unter Microsoft Graph's scopes.

Sie können der Ressource das Bereichsuffix /.default hinzufügen, um Ihre Apps von ADAL zu MSAL zu migrieren. Beispielsweise ist für den Ressourcenwert https://graph.microsoft.com der entsprechende Bereichswert https://graph.microsoft.com/.default. Wenn die Ressource nicht als URL vorliegt, sondern als Ressourcen-ID der Form XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, können Sie den Bereichswert dennoch als XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default verwenden.

Weitere Informationen zu den verschiedenen Arten von Bereichen finden Sie in den Artikeln "Berechtigungen und Zustimmung" in der Microsoft Identity Platform und den Bereichen für eine Web-API, die v1.0-Tokenartikel akzeptiert.

Kernklassen

In ADAL4J stellt die AuthenticationContext Klasse Ihre Verbindung mit dem Sicherheitstokendienst (Security Token Service, STS) oder autorisierungsserver über eine Autorität dar. MSAL für Java ist jedoch auf Clientanwendungen ausgelegt. Sie stellt zwei separate Klassen bereit: PublicClientApplication und ConfidentialClientApplication stellt Clientanwendungen dar. Letzteres stellt eine Anwendung dar, die so konzipiert ist, ConfidentialClientApplicationdass ein geheimer Schlüssel wie ein Anwendungsbezeichner für eine Daemon-App sicher verwaltet wird.

Die folgende Tabelle zeigt, welche ADAL4J-Funktionen welchen neuen MSAL-für-Java-Funktionen entsprechen:

IAccount anstelle von IUser

ADAL4J verwaltete Benutzer. Obwohl ein Benutzer einen einzelnen menschlichen oder Software-Agent darstellt, kann er über ein oder mehrere Konten im Microsoft Identitätssystem verfügen. Beispielsweise kann ein Benutzer mehrere Microsoft Entra ID, Azure AD B2C oder Microsoft persönliche Konten haben.

MSAL für Java definiert das Konzept von Account über die IAccount Schnittstelle. Dies ist eine bahnbrechende Änderung von ADAL4J. Es erfasst die Tatsache, dass derselbe Benutzer mehrere Konten haben kann, und vielleicht sogar in verschiedenen Microsoft Entra Verzeichnissen. MSAL für Java liefert in Gastszenarien bessere Informationen, da Informationen zum Heimatkonto bereitgestellt werden.

Persistenz des Cache

ADAL4J hat keine Unterstützung für den Tokencache. MSAL für Java fügt einen Tokencache hinzu, um die Verwaltung von Tokenlebensdauern zu vereinfachen, indem abgelaufene Token nach Möglichkeit automatisch aktualisiert und unnötige Aufforderungen zum Bereitstellen von Anmeldeinformationen verhindert werden.

Gemeinsame Autorität

Wenn Sie die https://login.microsoftonline.com/common Autorität verwenden, können sich Benutzer in Version 1.0 mit einem beliebigen Microsoft Entra Konto (für jede Organisation) anmelden.

Wenn Sie die https://login.microsoftonline.com/common Autorität in v2.0 verwenden, können sich Benutzer mit einer beliebigen Microsoft Entra Organisation oder sogar mit einem Microsoft persönlichen Konto (MSA) anmelden. Wenn Sie in MSAL für Java die Anmeldung auf ein beliebiges Microsoft Entra Konto einschränken möchten, verwenden Sie die https://login.microsoftonline.com/organizations Autorität (das gleiche Verhalten wie bei ADAL4J). Um eine Autorität anzugeben, legen Sie den authority Parameter in der PublicClientApplication.Builder Methode fest, wenn Sie eine PublicClientApplication Klasse instanziieren.

v1.0- und v2.0-Token

Der v1.0-Endpunkt (verwendet von ADAL) gibt nur v1.0-Token aus.

Der v2.0-Endpunkt (verwendet von MSAL) kann v1.0- und v2.0-Token ausgeben. Mit einer Eigenschaft des Anwendungsmanifests der Web-API können Entwickler auswählen, welche Tokenversion akzeptiert wird. Siehe accessTokenAcceptedVersion in der Referenzdokumentation zum Anwendungsmanifest.

Weitere Informationen zu v1.0- und v2.0-Token finden Sie unter Microsoft Entra Zugriffstoken.

Migration von ADAL zu MSAL

In ADAL4J wurden die Aktualisierungstoken verfügbar gemacht, wodurch Entwickler sie zwischenspeichern konnten. Sie würden dann AcquireTokenByRefreshToken() verwenden, um Lösungen zu ermöglichen, z. B. die Implementierung langlebiger Dienste, die Dashboards im Auftrag des Benutzers aktualisieren, wenn der Benutzer nicht mehr verbunden ist.

MSAL für Java macht Aktualisierungstoken aus Sicherheitsgründen nicht verfügbar. Stattdessen übernimmt MSAL das Aktualisieren von Token für Sie.

MSAL für Java verfügt über eine API, die es Ihnen ermöglicht, mit ADAL4J abgerufene Refreshtoken in das ClientApplication: RefreshTokenParameters zu migrieren. Mit dieser Methode können Sie das zuvor verwendete Aktualisierungstoken zusammen mit allen gewünschten Bereichen (Ressourcen) bereitstellen. Das Refresh-Token wird gegen ein neues ausgetauscht und für die Verwendung durch Ihre Anwendung zwischengespeichert.

Der folgende Codeausschnitt zeigt einen einfachen Codeausschnitt für die Migration in einer vertraulichen Clientanwendung:

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

Das IAuthenticationResult Gibt ein Zugriffstoken und ein ID-Token zurück, während Ihr neues Aktualisierungstoken im Cache gespeichert wird. Die Anwendung wird nun auch ein IAccount enthalten:

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

Um die Token zu verwenden, die sich jetzt im Cache befinden, rufen Sie Folgendes auf:

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