Rozdíly mezi aplikacemi ADAL.NET a MSAL.NET

Migrace aplikací z používání ADAL na používání msAL přináší výhody zabezpečení a odolnosti. Tento článek popisuje rozdíly mezi MSAL.NET a ADAL.NET. Ve většině případů chcete používat MSAL.NET a platformu Microsoft Identity Platform, což je nejnovější generace knihoven ověřování Microsoftu. Pomocí MSAL.NET získáte tokeny pro uživatele, kteří se přihlašují k aplikaci pomocí Azure AD (pracovních a školních účtů), účtů Microsoft (osobních) účtů (MSA) nebo Azure AD B2C.

Pokud už znáte ADAL.NET a koncový bod Azure AD pro vývojáře (verze 1.0), získáte informace o tom, co se liší od platformy Microsoft Identity Platform? Přesto musíte použít ADAL.NET, pokud se vaše aplikace potřebuje přihlásit uživatele pomocí starších verzí služby Active Directory Federation Services (ADFS). Další informace najdete v tématu Podpora ADFS.

ADAL NET MSAL NET
Balíčky NuGet a obory názvů ADAL byl spotřebován z balíčku NuGet Microsoft.IdentityModel.Clients.ActiveDirectory . Obor názvů byl Microsoft.IdentityModel.Clients.ActiveDirectory. Přidejte balíček NuGet Microsoft.Identity.Client a použijte Microsoft.Identity.Client obor názvů. Pokud vytváříte důvěrnou klientskou aplikaci, podívejte se na Microsoft.Identity.Web.
Obory a prostředky ADAL.NET získá tokeny pro prostředky. MSAL.NET získá tokeny pro obory. Několik přepsání MSAL.NET AcquireTokenXXX vyžaduje parametr s názvem scopes(IEnumerable<string> scopes). Tento parametr je jednoduchý seznam řetězců, které deklarují oprávnění a prostředky, které jsou požadovány. Známé obory jsou obory Microsoft Graphu. K prostředkům verze 1.0 můžete přistupovat také pomocí MSAL.NET.
Základní třídy ADAL.NET jako reprezentaci připojení ke službě tokenů zabezpečení (STS) nebo autorizačnímu serveru prostřednictvím autority použili AuthenticationContext . MSAL.NET je navržený pro klientské aplikace. Definuje IPublicClientApplication rozhraní pro veřejné klientské aplikace a IConfidentialClientApplication pro důvěrné klientské aplikace a také základní rozhraní IClientApplicationBase kontraktu společné pro oba typy aplikací.
Získání tokenu Ve veřejných klientech používá AcquireTokenAsync ADAL a AcquireTokenSilentAsync k ověřování volání. Ve veřejnýchklientch AcquireTokenInteractiveAcquireTokenSilent Parametry se liší od parametrů ADAL.

V důvěrných klientských aplikacích existují metody získávání tokenů s explicitním názvem v závislosti na scénáři. Dalším rozdílem je, že v MSAL.NET už nemusíte předávat ClientID aplikaci v každém volání AcquireTokenXX. Je ClientID nastaven pouze jednou při sestavování IPublicClientApplication nebo IConfidentialClientApplication.
IAccount a IUser ADAL definuje pojem uživatele prostřednictvím rozhraní IUser. Uživatel je však člověk nebo softwarový agent. Uživatel může například vlastnit jeden nebo více účtů na platformě Microsoft Identity Platform (několik účtů Azure AD, Azure AD B2C, osobní účty Microsoft). Uživatel může být zodpovědný také za jeden nebo více účtů Microsoft Identity Platform. MSAL.NET definuje koncept účtu (prostřednictvím rozhraní IAccount). Rozhraní IAccount představuje informace o jednom účtu. Uživatel může mít několik účtů v různých tenantech. MSAL.NET poskytuje lepší informace ve scénářích hosta, protože jsou poskytovány informace o domovském účtu. Můžete si přečíst další informace o rozdílech mezi IUser a IAccount.
Trvalost mezipaměti ADAL.NET umožňuje rozšířit TokenCache třídu tak, aby implementovaly požadované funkce trvalosti na platformách bez zabezpečeného úložiště (.NET Framework a .NET Core) pomocí BeforeAccessa metod.BeforeWrite Podrobnosti najdete v tématu Serializace mezipaměti tokenů v ADAL.NET. MSAL.NET vytvoří mezipaměť tokenu zapečetěnou třídu, čímž se odebere možnost ho rozšířit. Vaše implementace trvalosti mezipaměti tokenů musí být ve formě pomocné třídy, která komunikuje s zapečetěnou mezipaměť tokenů. Tato interakce je popsaná v serializaci mezipaměti tokenů v MSAL.NET článku. Serializace pro veřejnou klientskou aplikaci (viz mezipaměť tokenů pro veřejnou klientskou aplikaci) se liší od té pro důvěrnou klientskou aplikaci (viz mezipaměť tokenů pro webovou aplikaci nebo webové rozhraní API).
Společná autorita ADAL používá Azure AD v1.0. https://login.microsoftonline.com/common autorita v Azure AD verze 1.0 (kterou ADAL používá) umožňuje uživatelům přihlásit se pomocí libovolného účtu organizace AAD (pracovní nebo školní). Azure AD v1.0 neumožňuje přihlášení pomocí osobních účtů Microsoftu. Další informace najdete v tématu ověření autority v ADAL.NET. MSAL používá Azure AD verze 2.0. https://login.microsoftonline.com/common autorita ve službě Azure AD verze 2.0 (kterou používá MSAL) umožňuje uživatelům přihlásit se pomocí libovolného účtu AAD (pracovní nebo školní) nebo pomocí osobního účtu Microsoft. Pokud chcete omezit přihlášení jenom pomocí účtů organizace (pracovního nebo školního účtu) v MSAL, budete muset koncový bod použít https://login.microsoftonline.com/organizations . Podrobnosti najdete v parametru authority ve veřejné klientské aplikaci.

Podporované granty

Níže je souhrn porovnání MSAL.NET a ADAL.NET podporovaných grantů pro veřejné i důvěrné klientské aplikace.

Veřejné klientské aplikace

Následující obrázek shrnuje některé rozdíly mezi ADAL.NET a MSAL.NET pro veřejnou klientskou aplikaci.

Screenshot showing some of the differences between ADAL.NET and MSAL.NET for a public client application.

Tady jsou granty podporované v ADAL.NET a MSAL.NET pro desktopové a mobilní aplikace.

Oprávnění MSAL.NET ADAL.NET
Interaktivní Interaktivní získávání tokenů v MSAL.NET Interaktivní ověřování
Integrované ověřování systému Windows Integrované ověřování systému Windows Integrované ověřování ve Windows (Kerberos)
Uživatelské jméno / heslo Ověřování pomocí uživatelského jména a hesla Získání tokenů pomocí uživatelského jména a hesla
Tok kódu zařízení Tok kódu zařízení Profil zařízení pro zařízení bez webových prohlížečů

Důvěrné klientské aplikace

Následující obrázek shrnuje některé rozdíly mezi ADAL.NET a MSAL.NET pro důvěrnou klientskou aplikaci.

Screenshot showing some of the differences between ADAL.NET and MSAL.NET for a confidential client application.

Tady jsou granty podporované v aplikacích ADAL.NET, MSAL.NET a Microsoft.Identity.Web pro webové aplikace, webová rozhraní API a aplikace démona.

Typ aplikace Oprávnění MSAL.NET ADAL.NET
Webová aplikace, webové rozhraní API, démon Přihlašovací údaje klienta Toky přihlašovacích údajů klienta v MSAL.NET Toky přihlašovacích údajů klienta v ADAL.NET
Webové rozhraní API Jménem Jménem MSAL.NET Služba službám volá jménem uživatele s ADAL.NET
Webová aplikace Ověřovací kód Získání tokenů s autorizačními kódy ve webových aplikacích pomocí MSAL.NET Získání tokenů s autorizačními kódy ve webových aplikacích pomocí ADAL.NET

Migrace z ADAL 2.x s využitím obnovovacích tokenů

V ADAL.NET v2. X, obnovovací tokeny byly zpřístupněny, abyste mohli vyvíjet řešení týkající se použití těchto tokenů tak, že je uložíte do mezipaměti a použijete AcquireTokenByRefreshToken metody poskytované ADAL 2.x.

Některá z těchto řešení se používala ve scénářích, jako jsou:

  • Dlouhotrvající služby, které provádějí akce, včetně aktualizací řídicích panelů pro uživatele, když už nejsou uživatelé připojení nebo přihlášení k aplikaci.
  • Scénáře WebFarm pro povolení obnovení tokenu aktualizace do webové služby (ukládání do mezipaměti se provádí na straně klienta, šifrovaný soubor cookie a ne na straně serveru).

MSAL.NET nezpřístupňuje obnovovací tokeny z bezpečnostních důvodů. MSAL zpracovává obnovovací tokeny za vás.

Naštěstí MSAL.NET má rozhraní API, které umožňuje migrovat předchozí obnovovací tokeny (získané pomocí ADAL) do 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);

Pomocí této metody můžete zadat dříve použitý obnovovací token spolu s libovolnými obory (prostředky), které chcete. Obnovovací token se vymění za nový a uloží se do vaší aplikace.

Vzhledem k tomu, že tato metoda je určena pro scénáře, které nejsou typické, není snadno přístupný bez IConfidentialClientApplication prvního přetypování na IByRefreshToken.

Následující fragment kódu ukazuje kód migrace v důvěrné klientské aplikaci.

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 Načte obnovovací token uložený v určitém úložišti předchozí verzí aplikace, která se použila k použití ADAL 2.x. GetTokenCacheForSignedInUser deserializuje mezipaměť pro přihlášeného uživatele (jako důvěrné klientské aplikace by měly mít jednu mezipaměť na uživatele).

Přístupový token a token ID se vrátí v AuthenticationResult hodnotě, zatímco nový obnovovací token je uložený v mezipaměti. Tuto metodu můžete použít také pro různé scénáře integrace, ve kterých máte k dispozici obnovovací token.

tokeny v1.0 a v2.0

Existují dvě verze tokenů: tokeny v1.0 a tokeny verze 2.0. Koncový bod verze 1.0 (používaný knihovnou ADAL) generuje tokeny ID v1.0, zatímco koncový bod v2.0 (používaný nástrojem MSAL) generuje tokeny ID v2.0. Oba koncové body však generují přístupové tokeny verze tokenu, kterou webové rozhraní API přijímá. Vlastnost manifestu aplikace webového rozhraní API umožňuje vývojářům zvolit, která verze tokenu je přijata. Viz accessTokenAcceptedVersion referenční dokumentace k manifestu aplikace .

Další informace o přístupových tokenech verze 1.0 a v2.0 najdete v tématu Přístupové tokeny Azure Active Directory.

Výjimky

Požadované výjimky interakce

Pomocí MSAL.NET chytáte MsalUiRequiredException , jak je popsáno v části AcquireTokenSilent.

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

Podrobnosti najdete v tématu Zpracování chyb a výjimek v MSAL.NET

ADAL.NET měly méně explicitní výjimky. Pokud například tiché ověřování selhalo v ADAL, byl postup zachycení výjimky a vyhledání user_interaction_required kódu chyby:

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

Podrobnosti najdete v doporučeném vzoru získání tokenu ve veřejných klientských aplikacích s ADAL.NET.

Chování výzvy

Chování výzvy v MSAL.NET odpovídá chování výzvy v ADAL.NET:

ADAL.NET MSAL.NET Description
PromptBehavior.Auto NoPrompt Azure AD zvolí nejlepší chování (bezobslužné přihlašování uživatelů, pokud jsou přihlášení jenom pomocí jednoho účtu, nebo zobrazení selektoru účtu, pokud jsou přihlášení pomocí několika účtů).
PromptBehavior.Always ForceLogin Obnoví přihlašovací pole a vynutí uživatele, aby se znovu přihlásil k přihlašovacím údajům.
PromptBehavior.RefreshSession Consent Vynutí, aby uživatel znovu udělil souhlas se všemi oprávněními.
PromptBehavior.Never Never Nepoužívejte; místo toho použijte doporučený vzor pro veřejné klientské aplikace.
PromptBehavior.SelectAccount SelectAccount Zobrazí selektor účtu a vynutí uživatele, aby ho vybral.

Zpracování výjimek výzvy deklarací identity

V době, kdy azure AD získá token, vyvolá výjimku v případě, že prostředek vyžaduje více deklarací identity od uživatele (například dvoufaktorové ověřování).

V MSAL.NET se výjimky výzvy deklarací identity zpracovávají následujícím způsobem:

  • Povrchy Claims jsou v sadě MsalServiceException.
  • .WithClaim(claims) Existuje metoda, která se dá použít pro AcquireTokenXXX tvůrce.

Podrobnosti najdete v tématu Zpracování msalUiRequiredException.

V ADAL.NET byly výjimky výzvy deklarace identity zpracovávány následujícím způsobem:

  • AdalClaimChallengeException je výjimka (odvozená od AdalServiceException). Člen Claims obsahuje nějaký fragment JSON s deklaracemi identity, které se očekávají.
  • Veřejná klientská aplikace, která přijímá tuto výjimku, potřebovala volat přepsání AcquireTokenInteractive s parametrem deklarací identity. Toto přepsání AcquireTokenInteractive se ani nepokouší dostat do mezipaměti, protože to není nutné. Důvodem je, že token v mezipaměti nemá správné deklarace identity (jinak AdalClaimChallengeException by se nevyvolal). Proto není potřeba se podívat na mezipaměť. Tento ClaimChallengeException kód lze přijímat ve webovém rozhraní API, který provádí OBO, ale AcquireTokenInteractive musí být volána ve veřejné klientské aplikaci, která volá toto webové rozhraní API.

Podrobnosti včetně ukázek najdete v tématu zpracování AdalClaimChallengeException.

Obory

ADAL používá koncept prostředků s řetězcem resourceId , MSAL.NET, ale používá obory. Logika používaná službou Azure AD je následující:

  • Pro koncový bod ADAL (v1.0) s přístupovým tokenem v1.0 (jediný možný), aud=resource.
  • V případě koncového bodu MSAL (v2.0) s žádostí o přístupový token pro prostředek, který přijímá tokeny verze 2.0, aud=resource.AppId.
  • V případě koncového bodu MSAL (v2.0) požádáte o přístupový token pro prostředek, který přijímá přístupový token verze 1.0, Azure AD analyzuje požadovanou cílovou skupinu z požadovaného oboru. To provedete tak, že vezmete vše před posledním lomítkem a použijete ho jako identifikátor prostředku. Pokud například https://database.windows.net očekáváte cílovou skupinu https://database.windows.net/, budete muset požádat o rozsah https://database.windows.net//.default (všimněte si dvojité lomítko před ./default). To je znázorněno příklady 1 a 2 níže.

Příklad 1

Pokud chcete získat tokeny pro aplikaci, která přijímá tokeny verze 1.0 (například rozhraní Microsoft Graph API, což je https://graph.microsoft.com), musíte vytvořit scopes zřetězením požadovaného identifikátoru prostředku s požadovaným oprávněním OAuth2 pro daný prostředek.

Pokud například chcete získat přístup k názvu uživatele prostřednictvím webového rozhraní API verze 1.0, jehož identifikátor URI ID aplikace je ResourceId, chcete použít:

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

Pokud chcete číst a zapisovat pomocí MSAL.NET Azure Active Directory pomocí rozhraní Microsoft Graph API (https://graph.microsoft.com/), vytvořili byste seznam oborů, jako je v následujícím fragmentu kódu:

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

Příklad 2

Pokud id prostředku končí hodnotou /, při zápisu hodnoty oboru budete muset mít dvojitou hodnotu /. Pokud například chcete napsat obor odpovídající rozhraní API Azure Resource Manageru (https://management.core.windows.net/), požádejte o následující obor (všimněte si dvou lomítek).

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

Důvodem je to, že rozhraní API Resource Manageru očekává lomítko ve své deklaraci cílové skupiny (aud) a pak lomítko odděluje název rozhraní API od oboru.

Pokud chcete získat token pro všechny statické obory aplikace verze 1.0, vytvořte seznam oborů, jak je znázorněno v následujícím fragmentu kódu:

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

Pro tok přihlašovacích údajů klienta by také /.defaultbyl obor, který se má předat. Tento obor říká Službě Azure AD: "Všechna oprávnění na úrovni aplikace, ke kterým správce udělil souhlas v registraci aplikace.

Další kroky

Migrace aplikací z ADAL na MSALMigrate ADAL.NET důvěrných klientských aplikací pro použití MSAL.NET