A ADAL.NET és a MSAL.NET-alkalmazások közötti különbségek

Az alkalmazások migrálása az ADAL-ból az MSAL használatára biztonsági és rugalmassági előnyökkel jár. Ez a cikk a MSAL.NET és a ADAL.NET közötti különbségeket ismerteti. Minden új alkalmazásnak MSAL.NET és a Microsoft Identitásplatform kell használnia, amely a Microsoft hitelesítési kódtárak legújabb generációja. A MSAL.NET használatával jogkivonatokat szerezhet be az alkalmazásba bejelentkező felhasználók számára Azure AD (munkahelyi és iskolai fiókok), Microsoft (személyes) fiókok (MSA) vagy Azure AD B2C használatával. Ha ADAL.NET használó meglévő alkalmazással rendelkezik, migrálja azt MSAL.NET.

Továbbra is ADAL.NET kell használnia, ha az alkalmazásnak az Active Directory összevonási szolgáltatások (AD FS) (ADFS) korábbi verzióival kell bejelentkeznie a felhasználókba. További információ: ADFS-támogatás.

Előfeltételek

Tekintse át az MSAL áttekintését , ha többet szeretne megtudni az MSAL-ről.

Eltérések

ADAL NET MSAL NET
NuGet-csomagok és névterek Az ADAL-t a Microsoft használták fel. IdentityModel.Clients.ActiveDirectory NuGet-csomag. A névtér a következő volt Microsoft.IdentityModel.Clients.ActiveDirectory: . Adja hozzá a Microsoft. Identity.Client NuGet-csomag, és használja a Microsoft.Identity.Client névteret. Ha bizalmas ügyfélalkalmazást hoz létre, tekintse meg Microsoft. Identity.Web.
Hatókörök és erőforrások ADAL.NET jogkivonatokat szerez be az erőforrásokhoz. MSAL.NET jogkivonatokat szerez be a hatókörökhöz. Számos MSAL.NET AcquireTokenXXX felülbíráláshoz szükség van egy scopes(IEnumerable<string> scopes) nevű paraméterre. Ez a paraméter a kért engedélyeket és erőforrásokat deklaráló sztringek egyszerű listája. A jól ismert hatókörök a Microsoft Graph hatókörei. Az 1.0-s verziós erőforrásokat MSAL.NET is elérheti.
Alaposztályok ADAL.NET hitelesítésszolgáltatón keresztül használta az AuthenticationContext parancsot a biztonsági jogkivonat-szolgáltatáshoz (STS) vagy engedélyezési kiszolgálóhoz való kapcsolat ábrázolásához. MSAL.NET az ügyfélalkalmazások köré van tervezve. Meghatározza a IPublicClientApplication nyilvános ügyfélalkalmazások és IConfidentialClientApplication a bizalmas ügyfélalkalmazások felületeit, valamint a szerződés alapfelületét IClientApplicationBase , amely mindkét típusú alkalmazáshoz közös.
Jogkivonat beszerzése A nyilvános ügyfeleknél az ADAL és AcquireTokenSilentAsync a hitelesítési hívásokhoz használja AcquireTokenAsync azokat. A nyilvános ügyfeleknél az MSAL és AcquireTokenSilent ugyanazokat a hitelesítési hívásokat használjaAcquireTokenInteractive. A paraméterek eltérnek az ADAL-tól.

A Bizalmas ügyfélalkalmazásokban a forgatókönyvtől függően vannak explicit névvel rendelkező jogkivonat-beszerzési módszerek . Egy másik különbség az, hogy MSAL.NET már nem kell átadnia az ClientID alkalmazást minden AcquireTokenXX-hívásban. A ClientID beállítás csak egyszer van beállítva, amikor a vagy IConfidentialClientApplicationa vagy az elemet építi IPublicClientApplication be.
IAccount és IUser Az ADAL meghatározza a felhasználó fogalmát az IUser felületen keresztül. A felhasználó azonban emberi vagy szoftverügynök. Így a felhasználó egy vagy több fiókkal rendelkezhet a Microsoft Identitásplatform (több Azure AD fiók, Azure AD B2C, Microsoft személyes fiók). A felhasználó egy vagy több Microsoft Identitásplatform fiókért is felelős lehet. MSAL.NET definiálja a fiók fogalmát (az IAccount felületen keresztül). Az IAccount felület egyetlen fiók adatait jelöli. A felhasználó több fiókkal is rendelkezhet különböző bérlőkben. MSAL.NET jobb információkat nyújt a vendégforgatókönyvekben, mivel az otthoni fiók adatai meg lesznek adva. További információ az IUser és az IAccount közötti különbségekről.
Gyorsítótár-megőrzés ADAL.NET lehetővé teszi a osztály kiterjesztését a TokenCache kívánt adatmegőrzési funkciók biztonságos tárolás (.NET-keretrendszer és .NET core) nélküli platformokon való implementálásához a , és BeforeWrite metódusok BeforeAccesshasználatával. Részletekért lásd a jogkivonat-gyorsítótár szerializálását a ADAL.NET. MSAL.NET a tokengyorsítótárat lezárt osztálysá teszi, így nem tudja kiterjeszteni. Ezért a tokengyorsítótár-adatmegőrzés implementálásának egy segítő osztály formájában kell lennie, amely a lezárt jogkivonat-gyorsítótárral kommunikál. Ezt az interakciót a jogkivonat-gyorsítótár szerializálása ismerteti MSAL.NET cikkben. A nyilvános ügyfélalkalmazások szerializálása (lásd a nyilvános ügyfélalkalmazás jogkivonat-gyorsítótárát) eltér a bizalmas ügyfélalkalmazásokétól (lásd: webalkalmazás vagy webes API jogkivonat-gyorsítótára).
Közös hatóság Az ADAL Azure AD 1.0-s verziót használ. https://login.microsoftonline.com/commonAzure AD 1.0-s verzióban (amelyet az ADAL használ) lehetővé teszi, hogy a felhasználók bármely Azure AD szervezeti (munkahelyi vagy iskolai) fiókkal jelentkezzenek be. Azure AD 1.0-s verzió nem engedélyezi a bejelentkezést Microsoft személyes fiókkal. További információ: hitelesítés ADAL.NET. Az MSAL Azure AD 2.0-s verziót használ. https://login.microsoftonline.com/commonAzure AD v2.0-s verziójában (amelyet az MSAL használ) lehetővé teszi, hogy a felhasználók bármely Azure AD szervezeti (munkahelyi vagy iskolai) fiókkal vagy Microsoft személyes fiókkal jelentkezzenek be. Ha csak a szervezeti fiókokkal (munkahelyi vagy iskolai fiókkal) szeretné korlátozni a bejelentkezést az MSAL-ben, a https://login.microsoftonline.com/organizations végpontot kell használnia. Részletekért lásd a authoritynyilvános ügyfélalkalmazás paraméterét.

Támogatott támogatások

Az alábbiakban összefoglaljuk a nyilvános és bizalmas ügyfélalkalmazások MSAL.NET és ADAL.NET támogatott támogatásainak összehasonlítását.

Nyilvános ügyfélalkalmazások

Az alábbi kép összefoglalja a nyilvános ügyfélalkalmazások ADAL.NET és MSAL.NET közötti különbségeket.

Képernyőkép a nyilvános ügyfélalkalmazások ADAL.NET és MSAL.NET közötti különbségekről.

Íme az asztali és mobilalkalmazások ADAL.NET és MSAL.NET támogatott támogatásai.

Engedély MSAL.NET ADAL.NET
Interaktív Jogkivonatok interaktív beszerzése a MSAL.NET Interaktív hitelesítés
Integrált Windows-hitelesítés Integrált Windows-hitelesítés Integrált hitelesítés Windows rendszeren (Kerberos)
Felhasználónév/jelszó Felhasználónév-jelszó hitelesítés Jogkivonatok beszerzése felhasználónévvel és jelszóval
Eszközkód folyamata Eszközkód folyamata Eszközprofil webböngészővel nem rendelkező eszközökhöz

Bizalmas ügyfélalkalmazások

Az alábbi kép összefoglalja a bizalmas ügyfélalkalmazások ADAL.NET és MSAL.NET közötti különbségeket.

Képernyőkép a bizalmas ügyfélalkalmazások ADAL.NET és MSAL.NET közötti különbségekről.

Íme az ADAL.NET, MSAL.NET és Microsoft támogatott támogatások. Identity.Web webalkalmazásokhoz, webes API-khoz és démonalkalmazásokhoz.

Alkalmazás típusa Engedély MSAL.NET ADAL.NET
Webalkalmazás, webes API, démon Ügyfél hitelesítő adatai Ügyfél hitelesítő adatainak folyamatai a MSAL.NET Ügyfél hitelesítő adatainak folyamatai a ADAL.NET
Webes API A nevében A MSAL.NET nevében Szolgáltatáshívások a felhasználó nevében a ADAL.NET
Webalkalmazás Hitelesítési kód Jogkivonatok beszerzése engedélyezési kódokkal a webalkalmazásokban az A MSAL.NET Jogkivonatok beszerzése engedélyezési kódokkal a webalkalmazásokban ADAL.NET

Migrálás az ADAL 2.x-ről frissítési jogkivonatokkal

A ADAL.NET v2-ben. X, a frissítési jogkivonatok elérhetővé lettek téve, így az ADAL 2.x által biztosított módszerekkel olyan megoldásokat fejleszthet a jogkivonatok használatára vonatkozóan, amelyek gyorsítótárazásával és az AcquireTokenByRefreshToken ADAL 2.x által biztosított módszerekkel használhatók.

Ezen megoldások némelyikét olyan forgatókönyvekben használták, mint a következők:

  • Hosszú ideig futó szolgáltatások, amelyek műveleteket hajtanak végre, beleértve az irányítópultok frissítését a felhasználók számára, ha a felhasználók már nem csatlakoznak az alkalmazáshoz/jelentkeznek be.
  • WebFarm-forgatókönyvek, amelyek lehetővé teszik, hogy az ügyfél a frissítési jogkivonatot a webszolgáltatáshoz hozza (a gyorsítótárazás ügyféloldali, titkosított cookie-k és nem kiszolgálóoldali).

MSAL.NET biztonsági okokból nem teszi elérhetővé a frissítési jogkivonatokat. Az MSAL kezeli a frissítő jogkivonatokat.

Szerencsére MSAL.NET rendelkezik egy API-val, amely lehetővé teszi a korábbi frissítési jogkivonatok migrálását (az ADAL-jal beszerzett) a IConfidentialClientApplicationkövetkezőbe:

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

Ezzel a módszerrel megadhatja a korábban használt frissítési jogkivonatot a kívánt hatókörökkel (erőforrásokkal) együtt. A frissítési jogkivonat egy újra lesz cserélve, és az alkalmazásba lesz gyorsítótárazva.

Mivel ez a módszer nem tipikus forgatókönyvekhez készült, nem érhető el könnyen a IConfidentialClientApplication használatával anélkül, hogy először a-ra öntötte volna IByRefreshToken.

Az alábbi kódrészlet egy bizalmas ügyfélalkalmazás migrálási kódját mutatja be.

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 lekéri azt a frissítési jogkivonatot, amelyet az ADAL 2.x-et használó alkalmazás egy korábbi verziója tárolt egy tárolóban. GetTokenCacheForSignedInUser deszerializálja a bejelentkezett felhasználó gyorsítótárát (mivel a bizalmas ügyfélalkalmazásoknak felhasználónként egy gyorsítótárral kell rendelkezniük).

A rendszer egy hozzáférési jogkivonatot és egy azonosító jogkivonatot ad vissza az AuthenticationResult értékben, miközben az új frissítési jogkivonat a gyorsítótárban van tárolva. Ezt a módszert különböző integrációs forgatókönyvekhez is használhatja, ahol elérhető frissítési jogkivonat.

v1.0 és v2.0 tokenek

A tokeneknek két verziója van: 1.0-s és 2.0-s verziójú tokenek. Az 1.0-s verziójú végpont (amelyet az ADAL használ) 1.0-s verziójú azonosító jogkivonatokat bocsát ki, míg a v2.0 végpont (amelyet az MSAL használ) v2.0 azonosító jogkivonatokat bocsát ki. Azonban mindkét végpont a webes API által elfogadott jogkivonat verziójának hozzáférési jogkivonatait bocsátja ki. A webes API alkalmazásjegyzékének tulajdonsága lehetővé teszi a fejlesztők számára, hogy eldöntse, melyik jogkivonat-verziót fogadják el. Lásd accessTokenAcceptedVersion az alkalmazásjegyzék referenciadokumentációját.

Az 1.0-s és a 2.0-s verziós hozzáférési jogkivonatokkal kapcsolatos további információkért lásd: Azure Active Directory hozzáférési jogkivonatok.

Kivételek

Beavatkozáshoz szükséges kivételek

A MSAL.NET használatával a AcquireTokenSilent szakaszban leírtak szerint foghatja MsalUiRequiredException fel.

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

Részletekért lásd: Hibák és kivételek kezelése MSAL.NET

ADAL.NET kevésbé explicit kivételek voltak. Ha például az ADAL csendes hitelesítése sikertelen volt, az eljárás a kivételt észlelte, és megkereste a user_interaction_required hibakódot:

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

További részletekért tekintse meg az ajánlott mintát, amellyel jogkivonatot szerezhet be a nyilvános ügyfélalkalmazásokban ADAL.NET.

Kérési viselkedés

Az MSAL.NET parancssori viselkedése egyenértékű az ADAL.NET parancssori viselkedésének működésmódja:

ADAL.NET MSAL.NET Leírás
PromptBehavior.Auto NoPrompt Azure AD a legjobb viselkedést választja (ha csak egy fiókkal jelentkezik be, csendesen bejelentkezik a felhasználókba, vagy ha több fiókkal van bejelentkezve, akkor a fiókválasztót jeleníti meg).
PromptBehavior.Always ForceLogin Alaphelyzetbe állítja a bejelentkezési mezőt, és kényszeríti a felhasználót a hitelesítő adataik újbóli megadására.
PromptBehavior.RefreshSession Consent Kényszeríti a felhasználót, hogy minden engedélyhez újra hozzájáruljon.
PromptBehavior.Never Never Ne használja; ehelyett használja az ajánlott mintát a nyilvános ügyfélalkalmazásokhoz.
PromptBehavior.SelectAccount SelectAccount Megjeleníti a fiókválasztót, és kényszeríti a felhasználót egy fiók kiválasztására.

Jogcímkontraszt-kivételek kezelése

Jogkivonat beszerzésekor időnként Azure AD kivételt jelez arra az esetre, ha egy erőforrás több jogcímet igényel a felhasználótól (például kétfaktoros hitelesítés).

A MSAL.NET a jogcím-kihívás kivételei a következő módon kezelhetők:

  • A Claims a felületén jelenik meg.MsalServiceException
  • Van egy .WithClaim(claims) metódus, amely alkalmazható a AcquireTokenXXX szerkesztőkre.

További részletek: MsalUiRequiredException kezelése.

A ADAL.NET a jogcím-kihívás kivételeinek kezelése a következő módon megtörtént:

  • AdalClaimChallengeException kivétel (származtatása: AdalServiceException). A Claims tag tartalmaz néhány JSON-töredéket a jogcímekkel, amelyek a vártak.
  • A kivételt kapó nyilvános ügyfélalkalmazás a felülbírálás jogcímparaméterrel való meghívásához AcquireTokenInteractive szükséges. Ez a AcquireTokenInteractive felülbírálás nem is próbál meg a gyorsítótárba ütközni, mivel nincs rá szükség. Ennek az az oka, hogy a gyorsítótárban lévő token nem rendelkezik a megfelelő jogcímekkel (különben AdalClaimChallengeException nem lett volna dobva). Így nincs szükség a gyorsítótár megtekintésére. A ClaimChallengeException OBO-t végző WebAPI-ban fogadható, de ezt a AcquireTokenInteractive webes API-t meghívó nyilvános ügyfélalkalmazásban kell meghívni.

A részletekért, beleértve a mintákat is, lásd: az AdalClaimChallengeException kezelése.

Hatókörök

Az ADAL az erőforrások fogalmát használja sztringgel resourceId , MSAL.NET azonban hatóköröket használ. A Azure AD által használt logika a következő:

  • V1.0 hozzáférési jogkivonattal rendelkező ADAL -végpont (v1.0) esetén (az egyetlen lehetséges), aud=resource.
  • Az MSAL (2.0-s verziójú végpont) esetében, amely hozzáférési jogkivonatot kér egy 2.0-s jogkivonatot elfogadó erőforráshoz, aud=resource.AppIda következőt: .
  • Ha az MSAL (v2.0-végpont) hozzáférési jogkivonatot kér egy 1.0-s verziójú hozzáférési jogkivonatot elfogadó erőforráshoz, Azure AD elemzi a kívánt célközönséget a kért hatókörből. Ezt úgy végezheti el, hogy mindent az utolsó perjel előtt használ, és erőforrás-azonosítóként használja. Így ha https://database.windows.net a célközönségét https://database.windows.net/várja, akkor a hatókörét kell kérnie https://database.windows.net//.default (figyelje meg a dupla perjelet a ./default előtt). Ezt az alábbi 1. és 2. példa szemlélteti.

1\. példa

Ha egy 1.0-s verziójú jogkivonatokat elfogadó alkalmazáshoz szeretne jogkivonatokat beszerezni (például a Microsoft Graph API, azaz https://graph.microsoft.com), létre kell hoznia scopes egy kívánt erőforrás-azonosítót az erőforrás kívánt OAuth2-engedélyével való összefűzésével.

Ha például egy 1.0-s verziójú webes API-val szeretné elérni a felhasználó nevét, amelynek az alkalmazásazonosító URI-ja ResourceId, a következőt kell használnia:

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

Ha MSAL.NET Azure Active Directoryval szeretne olvasni és írni a Microsoft Graph API (https://graph.microsoft.com/) használatával, hozzon létre egy hatókörlistát, például az alábbi kódrészletben:

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

2\. példa

Ha a resourceId értéke "/" lesz, a hatókörérték írásakor dupla "/" értékkel kell rendelkeznie. Ha például meg szeretné írni az Azure Resource Manager API-nak megfelelő hatókört (https://management.core.windows.net/), kérje a következő hatókört (jegyezze fel a két perjelet).

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

Ennek az az oka, hogy a Resource Manager API perjelet vár a célközönség jogcímében (aud), majd egy perjel választja el az API-nevet a hatókörtől.

Ha egy 1.0-s verziós alkalmazás összes statikus hatóköréhez szeretne jogkivonatot beszerezni, akkor a hatókörlistát az alábbi kódrészletben látható módon hozza létre:

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

Az ügyfél hitelesítőadat-folyamata esetében az átengedendő hatókör is ./.default Ez a hatókör a következőhöz Azure AD: "az összes alkalmazásszintű engedély, amelyet a rendszergazda az alkalmazásregisztrációban adott meg.

Következő lépések

Alkalmazások migrálása az ADAL-ból az MSAL-beA ADAL.NET bizalmas ügyfélalkalmazások migrálása MSAL.NET