Verschillen tussen ADAL.NET- en MSAL.NET-apps

Het migreren van uw toepassingen van het gebruik van ADAL naar het gebruik van MSAL wordt geleverd met beveiligings- en tolerantievoordelen. In dit artikel vindt u een overzicht van de verschillen tussen MSAL.NET en ADAL.NET. Alle nieuwe toepassingen moeten gebruikmaken van MSAL.NET en de Microsoft identity platform, de nieuwste generatie van Microsoft-verificatiebibliotheken. Met MSAL.NET verkrijgt u tokens voor gebruikers die zich aanmelden bij uw toepassing met Microsoft Entra ID (werk- en schoolaccounts), Microsoft (persoonlijke) accounts (MSA) of Azure AD B2C. Als u een bestaande toepassing hebt die gebruikmaakt van ADAL.NET, migreert u deze naar MSAL.NET.

U moet nog steeds ADAL gebruiken.NET als uw toepassing gebruikers met eerdere versies van Active Directory Federation Services (ADFS) moet aanmelden. Zie ADFS-ondersteuning voor meer informatie.

Prerequisites

Bekijk het MSAL-overzicht voor meer informatie over MSAL.

Differences

Ondersteunde subsidies

Hieronder ziet u een overzicht van MSAL.NET en ADAL.NET ondersteunde subsidies voor zowel openbare als vertrouwelijke clienttoepassingen.

Openbare clienttoepassingen

In de volgende afbeelding ziet u een overzicht van enkele verschillen tussen ADAL.NET en MSAL.NET voor een openbare clienttoepassing.

Hier volgen de subsidies die worden ondersteund in ADAL.NET en MSAL.NET voor desktop- en mobiele toepassingen.

Vertrouwelijke clienttoepassingen

In de volgende afbeelding ziet u een overzicht van enkele verschillen tussen ADAL.NET en MSAL.NET voor een vertrouwelijke clienttoepassing.

Hier volgen de subsidies die worden ondersteund in ADAL.NET, MSAL.NET en Microsoft. Identity.Web voor webtoepassingen, web-API's en daemon-toepassingen.

Migreren vanuit ADAL 2.x met vernieuwingstokens

In ADAL.NET v2. X, de vernieuwingstokens werden weergegeven, zodat u oplossingen kunt ontwikkelen rond het gebruik van deze tokens door ze in de cache op te slaan en de AcquireTokenByRefreshToken methoden te gebruiken die worden geleverd door ADAL 2.x.

Sommige van deze oplossingen zijn gebruikt in scenario's zoals:

• Langlopende services die acties uitvoeren, waaronder het vernieuwen van dashboards voor de gebruikers wanneer de gebruikers niet langer zijn verbonden/aangemeld bij de app.
• WebFarm-scenario's voor het inschakelen van de client om het vernieuwingstoken naar de webservice te brengen (caching wordt uitgevoerd aan de clientzijde, versleutelde cookie en niet aan de serverzijde).

MSAL.NET geeft om veiligheidsredenen geen vernieuwingstokens weer. MSAL verwerkt het vernieuwen van tokens voor u.

Gelukkig heeft MSAL.NET een API waarmee u uw vorige vernieuwingstokens (verkregen met ADAL) kunt migreren naar het IConfidentialClientApplicationvolgende:

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

Met deze methode kunt u het eerder gebruikte vernieuwingstoken opgeven, samen met alle bereiken (resources) die u wilt. Het vernieuwingstoken wordt uitgewisseld voor een nieuw token en in de cache opgeslagen in uw toepassing.

Omdat deze methode bedoeld is voor scenario's die niet typisch zijn, is deze niet gemakkelijk toegankelijk met de IConfidentialClientApplication methode zonder deze eerst naar te IByRefreshTokencasten.

In het onderstaande codefragment ziet u een aantal migratiecode in een vertrouwelijke clienttoepassing.

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 haalt het vernieuwingstoken op dat is opgeslagen in een eerdere versie van de toepassing die is gebruikt voor het gebruik van ADAL 2.x. GetTokenCacheForSignedInUser ontserialiseerd een cache voor de aangemelde gebruiker (aangezien vertrouwelijke clienttoepassingen één cache per gebruiker moeten hebben).

Een toegangstoken en een id-token worden geretourneerd in de AuthenticationResult waarde terwijl het nieuwe vernieuwingstoken wordt opgeslagen in de cache. U kunt deze methode ook gebruiken voor verschillende integratiescenario's waarin u een vernieuwingstoken beschikbaar hebt.

v1.0- en v2.0-tokens

Er zijn twee versies van tokens: v1.0-tokens en v2.0-tokens. Het v1.0-eindpunt (gebruikt door ADAL) verzendt v1.0 ID-tokens terwijl het v2.0-eindpunt (gebruikt door MSAL) v2.0 ID-tokens verzendt. Beide eindpunten verzenden echter toegangstokens van de versie van het token dat door de web-API wordt geaccepteerd. 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 Microsoft Entra toegangstokens voor meer informatie over v1.0- en v2.0-toegangstokens.

Exceptions

Vereiste uitzonderingen voor interactie

Met behulp van MSAL.NET kunt u vangen MsalUiRequiredException zoals beschreven in AcquireTokenSilent

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

Zie Fouten en uitzonderingen afhandelen in MSAL.NET voor meer informatie

ADAL.NET had minder expliciete uitzonderingen. Wanneer bijvoorbeeld stille verificatie is mislukt in ADAL, was de procedure om de uitzondering te ondervangen en te zoeken naar de user_interaction_required foutcode:

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

Zie het aanbevolen patroon voor het verkrijgen van een token in openbare clienttoepassingen met ADAL.NET voor meer informatie.

Prompt gedrag

Promptgedrag in MSAL.NET is gelijk aan promptgedrag in ADAL.NET:

Uitzonderingen voor claimuitdaging afhandelen

Wanneer een token wordt opgehaald, genereert Microsoft Entra ID een uitzondering wanneer een resource meer claims van de gebruiker vereist (bijvoorbeeld tweeledige verificatie).

In MSAL.NET worden claimuitdagingsuitzonderingsuitzondering op de volgende manier afgehandeld:

• De Claims zijn opgedoken in de MsalServiceException.
• Er is een WithClaims(String) methode die kan worden toegepast op de AcquireTokenXXX opbouwfuncties.

Zie MsalUiRequiredException verwerken voor meer informatie.

In ADAL.NET werden uitzonderingen voor claimuitdagingen op de volgende manier afgehandeld:

• AdalClaimChallengeException is een uitzondering (afgeleid van AdalServiceException). Het Claims lid bevat een JSON-fragment met de claims, die worden verwacht.
• De openbare clienttoepassing die deze uitzondering ontvangt, moet worden aangeroepen om de AcquireTokenInteractive onderdrukking met een claimparameter aan te roepen. Deze onderdrukking probeert AcquireTokenInteractive niet eens de cache te raken, omdat dit niet nodig is. De reden hiervoor is dat het token in de cache niet beschikt over de juiste claims (anders zou er AdalClaimChallengeException geen token zijn gegenereerd). Daarom hoeft u de cache niet te bekijken. De ClaimChallengeException kan worden ontvangen in een WebAPI met OBO, maar de AcquireTokenInteractive moet worden aangeroepen in een openbare clienttoepassing die deze web-API aanroept.

Zie AdalClaimChallengeException voor meer informatie, waaronder voorbeelden.

Toepassingsgebieden

ADAL maakt gebruik van het concept van resources met resourceId tekenreeksen, MSAL.NET maakt echter gebruik van bereiken. De logica die door Microsoft Entra ID wordt gebruikt, is als volgt:

• Voor ADAL-eindpunt (v1.0) met een v1.0-toegangstoken (het enige mogelijke), aud=resource.
• Voor MSAL (v2.0-eindpunt) waarin een toegangstoken wordt gevraagd voor een resource die v2.0-tokens accepteert, aud=resource.AppId.
• Voor MSAL (v2.0-eindpunt) waarbij een toegangstoken wordt gevraagd voor een resource die een v1.0-toegangstoken accepteert, Microsoft Entra ID de gewenste doelgroep parseert vanuit het aangevraagde bereik. Dit wordt gedaan door alles te nemen vóór de laatste slash en deze te gebruiken als de resource-id. https://database.windows.net Als u een doelgroep https://database.windows.net/verwacht, moet u daarom een bereik aanvragen https://database.windows.net//.default (let op de dubbele slash vóór ./default). Dit wordt geïllustreerd door voorbeelden 1 en 2 hieronder.

Voorbeeld 1

Als u tokens wilt verkrijgen voor een toepassing die v1.0-tokens accepteert (bijvoorbeeld de Microsoft Graph API, dat wil https://graph.microsoft.comgezegd), moet u een scopes gewenste resource-id samenvoegen met een gewenste OAuth2-machtiging voor die resource.

Als u bijvoorbeeld toegang wilt krijgen tot de naam van de gebruiker via een v1.0-web-API waarvan de app-id-URI is ResourceId, wilt u het volgende gebruiken:

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

Als u wilt lezen en schrijven met MSAL.NET Microsoft Entra ID met behulp van de Microsoft Graph API (https://graph.microsoft.com/), maakt u een lijst met bereiken, zoals in het onderstaande codefragment:

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

Voorbeeld 2

Als resourceId eindigt op een '/', moet u een dubbele '/' hebben bij het schrijven van de bereikwaarde. Als u bijvoorbeeld het bereik wilt schrijven dat overeenkomt met de Azure Resource Manager-API (https://management.core.windows.net/), vraagt u het volgende bereik aan (let op de twee slashes).

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

Dit komt doordat de Resource Manager-API een slash verwacht in de doelgroepclaim (aud) en er vervolgens een slash is om de API-naam van het bereik te scheiden.

Als u een token wilt verkrijgen voor alle statische bereiken van een v1.0-toepassing, maakt u de lijst met bereiken, zoals wordt weergegeven in het onderstaande codefragment:

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

Voor een clientreferentiestroom is /.defaulthet bereik dat moet worden doorgegeven ook. Dit bereik geeft aan Microsoft Entra ID: 'alle machtigingen op app-niveau waarvoor de beheerder toestemming heeft gegeven in de toepassingsregistratie.

Volgende stappen 

Migreer uw apps van ADAL naar MSALMigrate your ADAL.NET confidential client apps to use MSAL.NET