Skillnader mellan ADAL.NET- och MSAL.NET-appar

Att migrera dina program från att använda ADAL till att använda MSAL medför säkerhets- och återhämtningsfördelar. Den här artikeln beskriver skillnaderna mellan MSAL.NET och ADAL.NET. Alla nya program bör använda MSAL.NET och Microsofts identitetsplattform, som är den senaste generationen av Microsoft-autentiseringsbibliotek. Med MSAL.NET skaffar du token för användare som loggar in i ditt program med Microsoft Entra ID (arbets- och skolkonton), Microsoft (personliga) konton (MSA) eller Azure AD B2C. Om du har ett befintligt program som använder ADAL.NET migrerar du det till MSAL.NET.

Du måste fortfarande använda ADAL.NET om ditt program behöver logga in användare med tidigare versioner av Active Directory Federation Services (ADFS) (ADFS). Mer information finns i ADFS-stöd.

Förutsättningar

Gå igenom MSAL-översikten om du vill veta mer om MSAL.

Differences

Bidrag som stöds

Nedan visas en sammanfattning som jämför MSAL.NET och ADAL.NET som stöds för både offentliga och konfidentiella klientprogram.

Offentliga klientprogram

Följande bild sammanfattar några av skillnaderna mellan ADAL.NET och MSAL.NET för ett offentligt klientprogram.

Här är de bidrag som stöds i ADAL.NET och MSAL.NET för skrivbords- och mobilprogram.

Konfidentiella klientprogram

Följande bild sammanfattar några av skillnaderna mellan ADAL.NET och MSAL.NET för ett konfidentiellt klientprogram.

Här är de bidrag som stöds i ADAL.NET, MSAL.NET och Microsoft. Identity.Web för webbprogram, webb-API:er och daemonprogram.

Migrera från ADAL 2.x med uppdateringstoken

I ADAL.NET v2. X, uppdateringstoken exponerades så att du kan utveckla lösningar kring användningen av dessa token genom att cachelagra dem och använda de AcquireTokenByRefreshToken metoder som tillhandahålls av ADAL 2.x.

Några av dessa lösningar användes i scenarier som:

• Långvariga tjänster som utför åtgärder, inklusive uppdatering av instrumentpaneler för användarna när användarna inte längre är anslutna/inloggade i appen.
• WebFarm-scenarier där klienten kan ta uppdateringstoken till webbtjänsten (cachelagring görs på klientsidan, krypterad cookie och inte på serversidan).

MSAL.NET exponerar inte uppdateringstoken av säkerhetsskäl. MSAL hanterar uppdateringstoken åt dig.

Lyckligtvis har MSAL.NET ett API som gör att du kan migrera dina tidigare uppdateringstoken (hämtas med ADAL) till IConfidentialClientApplication:

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

Med den här metoden kan du ange den tidigare använda uppdateringstoken tillsammans med eventuella omfång (resurser) som du vill ha. Uppdateringstoken kommer att bytas ut mot en ny och cachelagras i ditt program.

Eftersom den här metoden är avsedd för scenarier som inte är typiska är den inte lätt åtkomlig med IConfidentialClientApplication utan att först casta den till IByRefreshToken.

Kodfragmentet nedan visar lite migreringskod i ett konfidentiellt klientprogram.

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 hämtar uppdateringstoken som lagrades i viss lagring av en tidigare version av programmet som använde ADAL 2.x. GetTokenCacheForSignedInUser deserialiserar en cache för den inloggade användaren (eftersom konfidentiella klientprogram bör ha en cache per användare).

En åtkomsttoken och en ID-token returneras i AuthenticationResult värdet medan den nya uppdateringstoken lagras i cacheminnet. Du kan också använda den här metoden för olika integreringsscenarier där du har en uppdateringstoken tillgänglig.

v1.0- och v2.0-token

Det finns två versioner av token: v1.0-token och v2.0-token. V1.0-slutpunkten (används av ADAL) genererar v1.0-ID-token medan v2.0-slutpunkten (används av MSAL) genererar v2.0 ID-token. Båda slutpunkterna genererar dock åtkomsttoken för den version av token som webb-API:et accepterar. Med en egenskap för webb-API:ets programmanifest kan utvecklare välja vilken version av token som godkänns. Se accessTokenAcceptedVersion referensdokumentationen för programmanifestet .

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

undantag

Undantag som krävs för interaktion

Med hjälp av MSAL.NET fångar MsalUiRequiredException du enligt beskrivningen i AcquireTokenSilent

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

Mer information finns i Hantera fel och undantag i MSAL.NET

ADAL.NET hade mindre explicita undantag. När tyst autentisering till exempel misslyckades i ADAL var proceduren att fånga undantaget och leta user_interaction_required efter felkoden:

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

Mer information finns i det rekommenderade mönstret för att hämta en token i offentliga klientprogram med ADAL.NET.

Snabbt beteende

Fråga beteende i MSAL.NET motsvarar fråga beteende i ADAL.NET:

Hantera undantag för anspråksutmaning

Ibland när du hämtar en token genererar Microsoft Entra ID ett undantag om en resurs kräver fler anspråk från användaren (till exempel tvåfaktorautentisering).

I MSAL.NET hanteras undantag för anspråksutmaning på följande sätt:

• Är Claims ytbehandlade i MsalServiceException.
• Det finns en WithClaims(String) metod som kan tillämpas på byggarna AcquireTokenXXX .

Mer information finns i Hantera MsalUiRequiredException.

I ADAL.NET hanterades undantag för anspråksutmaning på följande sätt:

• AdalClaimChallengeException är ett undantag (härleds från AdalServiceException). Medlemmen Claims innehåller ett JSON-fragment med anspråken, som förväntas.
• Det offentliga klientprogram som tar emot det här undantaget behövde anropa åsidosättningen AcquireTokenInteractive med en anspråksparameter. Den här åsidosättningen av AcquireTokenInteractive försöker inte ens träffa cacheminnet eftersom det inte är nödvändigt. Anledningen är att token i cacheminnet inte har rätt anspråk (annars skulle en AdalClaimChallengeException inte ha genererats). Därför behöver du inte titta på cacheminnet. ClaimChallengeException Kan tas emot i en WebAPI som gör OBO, men måste anropas i ett offentligt klientprogram som anropar det här webb-API:etAcquireTokenInteractive.

Mer information, inklusive exempel, finns i hantera AdalClaimChallengeException.

Scopes

ADAL använder begreppet resurser med resourceId sträng, MSAL.NET använder dock omfång. Logiken som används av Microsoft Entra ID är följande:

• För ADAL-slutpunkten (v1.0) med en v1.0-åtkomsttoken (det enda möjliga), aud=resource.
• För MSAL (v2.0-slutpunkt) frågar en åtkomsttoken för en resurs som accepterar v2.0-token, aud=resource.AppId.
• För MSAL (v2.0-slutpunkt) som ber om en åtkomsttoken för en resurs som accepterar en v1.0-åtkomsttoken parsar Microsoft Entra ID den önskade målgruppen från det begärda omfånget. Detta görs genom att ta allt före det sista snedstrecket och använda det som resursidentifierare. https://database.windows.net Om du förväntar dig en målgrupp på https://database.windows.net/måste du därför begära ett omfång https://database.windows.net//.default på (observera det dubbla snedstrecket före ./default). Detta illustreras av exemplen 1 och 2 nedan.

Exempel 1

Om du vill hämta token för ett program som accepterar v1.0-token (till exempel Microsoft Graph API, vilket är https://graph.microsoft.com), måste du skapa scopes genom att sammanfoga en önskad resursidentifierare med önskad OAuth2-behörighet för resursen.

Om du till exempel vill komma åt namnet på användaren via ett v1.0-webb-API vars app-ID-URI är ResourceIdvill du använda:

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

Om du vill läsa och skriva med MSAL.NET Microsoft Entra ID med hjälp av Microsoft Graph API (https://graph.microsoft.com/) skapar du en lista med omfång som i kodfragmentet nedan:

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

Exempel 2

Om resourceId slutar med ett "/" måste du ha ett dubbelt "/" när du skriver omfångsvärdet. Om du till exempel vill skriva omfånget som motsvarar Azure Resource Manager-API:et (https://management.core.windows.net/) begär du följande omfång (observera de två snedstrecken).

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

Det beror på att Resource Manager-API:et förväntar sig ett snedstreck i målgruppsanspråket (aud), och sedan finns det ett snedstreck för att skilja API-namnet från omfånget.

Om du vill hämta en token för alla statiska omfång för ett v1.0-program skapar du din omfångslista enligt kodfragmentet nedan:

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

För ett flöde för klientautentiseringsuppgifter skulle omfånget som ska skickas också vara /.default. Det här omfånget uppmanar till Microsoft Entra ID: "alla behörigheter på appnivå som administratören har samtyckt till i programregistreringen.

Nästa steg

Migrera dina appar från ADAL till MSALMigrera dina ADAL.NET konfidentiella klientappar för att använda MSAL.NET