Unterschiede zwischen ADAL.NET und MSAL.NET Apps

Die Migration Ihrer Anwendungen von der Verwendung von ADAL zur Verwendung von MSAL bietet Vorteile von Sicherheit und Resilienz. In diesem Artikel werden Unterschiede zwischen MSAL.NET und ADAL.NET beschrieben. Alle neuen Anwendungen sollten MSAL.NET und die Microsoft Identity Platform verwenden, die die neueste Generation von Microsoft-Authentifizierungsbibliotheken ist. Mit MSAL.NET erwerben Sie Token für Benutzer, die sich mit Microsoft Entra ID (Geschäfts- und Schulkonten), Microsoft (persönliche) Konten (MSA) oder Azure AD B2C bei Ihrer Anwendung anmelden. Wenn Sie über eine vorhandene Anwendung verfügen, die ADAL.NET verwendet, migrieren Sie sie zu MSAL.NET.

Sie müssen weiterhin ADAL verwenden.NET wenn Ihre Anwendung Benutzer mit früheren Versionen von Active Directory-Verbunddienste (AD FS) (ADFS) anmelden muss. Weitere Informationen finden Sie unter ADFS-Unterstützung.

Voraussetzungen

Lesen Sie die MSAL-Übersicht , um mehr über MSAL zu erfahren.

Unterschiede

Unterstützte Finanzhilfen

Nachfolgend finden Sie eine Zusammenfassung MSAL.NET und ADAL.NET unterstützte Finanzhilfen für öffentliche und vertrauliche Clientanwendungen.

Öffentliche Clientanwendungen

Die folgende Abbildung fasst einige der Unterschiede zwischen ADAL.NET und MSAL.NET für eine öffentliche Clientanwendung zusammen.

Hier sind die in ADAL.NET und MSAL.NET für Desktop- und Mobile-Anwendungen unterstützten Finanzhilfen.

Vertrauliche Clientanwendungen

Die folgende Abbildung fasst einige der Unterschiede zwischen ADAL.NET und MSAL.NET für eine vertrauliche Clientanwendung zusammen.

Hier sind die in ADAL.NET, MSAL.NET und Microsoft unterstützten Finanzhilfen. Identity.Web für Webanwendungen, Web-APIs und Daemon-Anwendungen.

Migrieren von ADAL 2.x mit Aktualisierungstoken

In ADAL.NET v2. X, die Aktualisierungstoken wurden verfügbar gemacht, sodass Sie Lösungen für die Verwendung dieser Token entwickeln können, indem Sie sie zwischenspeichern und die AcquireTokenByRefreshToken von ADAL 2.x bereitgestellten Methoden verwenden.

Einige dieser Lösungen wurden in Szenarien verwendet, z. B.:

• Lange ausgeführte Dienste, die Aktionen ausführen, einschließlich der Aktualisierung von Dashboards für die Benutzer, wenn die Benutzer nicht mehr mit der App verbunden/angemeldet sind.
• WebFarm-Szenarien, mit denen der Client das Aktualisierungstoken in den Webdienst übertragen kann (Zwischenspeichern erfolgt clientseitig, verschlüsseltes Cookie und nicht serverseitig).

MSAL.NET macht Aktualisierungstoken aus Sicherheitsgründen nicht verfügbar. MSAL behandelt die Aktualisierungstoken für Sie.

Glücklicherweise verfügt MSAL.NET über eine API, mit der Sie Ihre vorherigen Aktualisierungstoken (erworben mit ADAL) in folgendes IConfidentialClientApplicationmigrieren können:

/// <summary>
/// Acquires an access token from an existing refresh token and stores it and the refresh token into
/// the application user token cache, where it will be available for further AcquireTokenSilent calls.
/// This method can be used in migration to MSAL from ADAL v2 and in various integration
/// scenarios where you have a RefreshToken available.
/// (see https://aka.ms/msal-net-migration-adal2-msal2)
/// </summary>
/// <param name="scopes">Scope to request from the token endpoint.
/// Setting this to null or empty will request an access token, refresh token and ID token with default scopes</param>
/// <param name="refreshToken">The refresh token from ADAL 2.x</param>
IByRefreshToken.AcquireTokenByRefreshToken(IEnumerable<string> scopes, string refreshToken);

Mit dieser Methode können Sie das zuvor verwendete Aktualisierungstoken zusammen mit allen gewünschten Bereichen (Ressourcen) bereitstellen. Das Aktualisierungstoken wird für einen neuen ausgetauscht und in Ihrer Anwendung zwischengespeichert.

Da diese Methode für Szenarien vorgesehen ist, die nicht typisch sind, ist sie nicht leicht zugänglich mit der IConfidentialClientApplication ohne die erste Umwandlung.IByRefreshToken

Der folgende Codeausschnitt zeigt einen Migrationscode in einer vertraulichen Clientanwendung.

TokenCache userCache = GetTokenCacheForSignedInUser();
string rt = GetCachedRefreshTokenForSignedInUser();

IConfidentialClientApplication app;
app = ConfidentialClientApplicationBuilder.Create(clientId)
 .WithAuthority(Authority)
 .WithRedirectUri(RedirectUri)
 .WithClientSecret(ClientSecret)
 .Build();
IByRefreshToken appRt = app as IByRefreshToken;

AuthenticationResult result = await appRt.AcquireTokenByRefreshToken(null, rt)
                                         .ExecuteAsync()
                                         .ConfigureAwait(false);

GetCachedRefreshTokenForSignedInUser Ruft das Aktualisierungstoken ab, das in einem Speicher von einer früheren Version der Anwendung gespeichert wurde, die für die Verwendung von ADAL 2.x verwendet wurde. GetTokenCacheForSignedInUser deserialisiert einen Cache für den angemeldeten Benutzer (da vertrauliche Clientanwendungen einen Cache pro Benutzer haben sollten).

Ein Zugriffstoken und ein ID-Token werden im AuthenticationResult Wert zurückgegeben, während das neue Aktualisierungstoken im Cache gespeichert wird. Sie können diese Methode auch für verschiedene Integrationsszenarien verwenden, in denen Ein Aktualisierungstoken verfügbar ist.

v1.0- und v2.0-Token

Es gibt zwei Versionen von Token: v1.0-Token und v2.0-Token. Der v1.0-Endpunkt (verwendet von ADAL) gibt v1.0-ID-Token aus, während der v2.0-Endpunkt (verwendet von MSAL) v2.0-ID-Token ausgibt. Beide Endpunkte geben jedoch Zugriffstoken der Version des Tokens aus, das die Web-API akzeptiert. Mit einer Eigenschaft des Anwendungsmanifests der Web-API können Entwickler auswählen, welche Tokenversion akzeptiert wird. Weitere Informationen finden Sie accessTokenAcceptedVersion in der Referenzdokumentation zum Anwendungsmanifest .

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

Ausnahmen

Erforderliche Interaktions ausnahmen

Mithilfe von MSAL.NET können Sie wie in AcquireTokenSilent beschrieben abfangenMsalUiRequiredException.

catch(MsalUiRequiredException exception)
{
 try {"try to authenticate interactively"}
}

Ausführliche Informationen finden Sie unter Behandeln von Fehlern und Ausnahmen in MSAL.NET

ADAL.NET hatte weniger explizite Ausnahmen. Wenn bei der automatischen Authentifizierung in ADAL beispielsweise ein Fehler aufgetreten ist, sollte die Ausnahme erfasst und nach dem user_interaction_required Fehlercode gesucht werden:

catch(AdalException exception)
{
 if (exception.ErrorCode == "user_interaction_required")
 {
  try
  {“try to authenticate interactively”}}
 }
}

Ausführliche Informationen finden Sie im empfohlenen Muster zum Abrufen eines Tokens in öffentlichen Clientanwendungen mit ADAL.NET.

Promptes Verhalten

Das Eingabeaufforderungsverhalten in MSAL.NET entspricht dem Eingabeaufforderungsverhalten in ADAL.NET:

Behandeln von Ausnahmen für Anspruchsabfragen

Beim Abrufen eines Tokens löst Microsoft Entra ID eine Ausnahme aus, falls eine Ressource mehr Ansprüche vom Benutzer erfordert (z. B. zweistufige Authentifizierung).

In MSAL.NET werden Ausnahmen von Anspruchsabfragen wie folgt behandelt:

• Die Claims werden in der MsalServiceException.
• Es gibt eine WithClaims(String) Methode, die auf die AcquireTokenXXX Generatoren angewendet werden kann.

Ausführliche Informationen finden Sie unter "Handling MsalUiRequiredException".

In ADAL.NET wurden Ausnahmen von Anspruchsabfragen wie folgt behandelt:

• AdalClaimChallengeException ist eine Ausnahme (ableiten von AdalServiceException). Das Claims Element enthält einige JSON-Fragmente mit den Ansprüchen, die erwartet werden.
• Die öffentliche Clientanwendung, die diese Ausnahme empfängt, muss die AcquireTokenInteractive Außerkraftsetzung mit einem Anspruchsparameter aufrufen. Diese Außerkraftsetzung AcquireTokenInteractive versucht nicht einmal, den Cache zu treffen, da es nicht erforderlich ist. Der Grund dafür ist, dass das Token im Cache nicht über die richtigen Ansprüche verfügt (andernfalls wäre ein AdalClaimChallengeException Fehler nicht ausgelöst worden). Daher ist es nicht erforderlich, den Cache zu betrachten. Die ClaimChallengeException kann in einer WebAPI empfangen werden, die OBO ausführt, die jedoch AcquireTokenInteractive in einer öffentlichen Clientanwendung aufgerufen werden muss, die diese Web-API aufruft.

Ausführliche Informationen finden Sie unter " Behandeln von AdalClaimChallengeException".

Geltungsbereiche

ADAL verwendet das Konzept von Ressourcen mit resourceId Zeichenfolge, MSAL.NET verwendet jedoch Bereiche. Die von Microsoft Entra ID verwendete Logik lautet wie folgt:

• Für ADAL -Endpunkt (v1.0) mit einem v1.0-Zugriffstoken (das einzige möglich), aud=resource.
• Für MSAL (v2.0-Endpunkt) wird ein Zugriffstoken für eine Ressource gefragt, die v2.0-Token akzeptiert. aud=resource.AppId
• Für MSAL (v2.0-Endpunkt) wird ein Zugriffstoken für eine Ressource angefordert, die ein v1.0-Zugriffstoken akzeptiert, Microsoft Entra ID die gewünschte Zielgruppe aus dem angeforderten Bereich analysiert. Dies geschieht, indem alles vor dem letzten Schrägstrich verwendet und als Ressourcenbezeichner verwendet wird. Wenn eine Zielgruppe https://database.windows.net/davon https://database.windows.net erwartet wird, müssen Sie einen Bereich https://database.windows.net//.default anfordern (beachten Sie den Doppelten Schrägstrich vor ./default). Dies wird anhand der Beispiele 1 und 2 unten veranschaulicht.

Beispiel 1

Wenn Sie Token für eine Anwendung abrufen möchten, die v1.0-Token akzeptiert (z. B. microsoft Graph-API), müssen Sie erstellenscopes, https://graph.microsoft.comindem Sie einen gewünschten Ressourcenbezeichner mit einer gewünschten OAuth2-Berechtigung für diese Ressource verketten.

Um beispielsweise über eine v1.0-Web-API auf den Namen des Benutzers zuzugreifen, dessen App-ID-URI lautet ResourceId, sollten Sie Folgendes verwenden:

var scopes = new [] { ResourceId+"/user_impersonation" };

Wenn Sie mit MSAL.NET Microsoft Entra ID mithilfe von Microsoft Graph-API (https://graph.microsoft.com/) lesen und schreiben möchten, erstellen Sie eine Liste von Bereichen wie im folgenden Codeausschnitt:

string ResourceId = "https://graph.microsoft.com/"; 
string[] scopes = { ResourceId + "Directory.Read", ResourceId + "Directory.Write" }

Beispiel 2

Wenn "resourceId" mit einem "/" endet, müssen Sie beim Schreiben des Bereichswerts über ein doppeltes "/" verfügen. Wenn Sie beispielsweise den Bereich schreiben möchten, der der Azure Resource Manager-API (https://management.core.windows.net/) entspricht, fordern Sie den folgenden Bereich an (beachten Sie die beiden Schrägstriche).

var resource = "https://management.core.windows.net/"
var scopes = new[] {"https://management.core.windows.net//user_impersonation"};
var result = await app.AcquireTokenInteractive(scopes).ExecuteAsync();

// then call the API: https://management.azure.com/subscriptions?api-version=2016-09-01

Dies liegt daran, dass die Resource Manager-API einen Schrägstrich in seinem Zielgruppenanspruch (aud) erwartet, und dann gibt es einen Schrägstrich, um den API-Namen vom Bereich zu trennen.

Wenn Sie ein Token für alle statischen Bereiche einer v1.0-Anwendung abrufen möchten, erstellen Sie die Bereichsliste wie im folgenden Codeausschnitt gezeigt:

ResourceId = "someAppIDURI";
var scopes = new [] { ResourceId+"/.default" };

Bei einem Clientanmeldeinformationsfluss wäre der zu übergebende Bereich ebenfalls /.default. Dieser Bereich weist Microsoft Entra ID an: "Alle Berechtigungen auf App-Ebene, denen der Administrator in der Anwendungsregistrierung zugestimmt hat.

Nächste Schritte

Migrieren Ihrer Apps von ADAL zu MSAL MigrierenSie Ihre ADAL.NET vertraulichen Client-Apps, um MSAL.NET