الاختلافات بين تطبيقات ADAL.NET وتطبيقات MSAL.NET

يأتي ترحيل التطبيقات من استخدام ADAL إلى استخدام MSAL مع مزايا الأمان والمرونة. توضح هذه المقالة الاختلافات بين تطبيقات MSAL.NET وتطبيقات ADAL.NET. في معظم الحالات، تريد استخدام تطبيقات MSAL.NET والنظام الأساسي للهوية في Microsoft، وهو أحدث جيل من مكتبات مصادقة Microsoft. باستخدام MSAL.NET، يمكنك الحصول على رموز مميزة للمستخدمين الذين يسجلون الدخول إلى التطبيق الخاص بك مع AAD (دليل Azure النشط) (حسابات العمل والمدرسة)، حسابات Microsoft (الشخصية) (MSA)، أو متاجرة عمل-مستهلك Azure AD.

إذا كنت على دراية بطبيقات ADAL.NET ونقطة نهاية AAD (دليل Azure النشط) للمطورين (v1.0)، فتعرف على ما هو مختلف عن النظام الأساسي للهوية في Microsoft؟. لا تزال بحاجة إلى استخدام ADAL.NET إذا كان التطبيق الخاص بك يحتاج إلى تسجيل الدخول للمستخدمين الذين لديهم إصدارات سابقة من خدمات الأمان المشترك لـ Active Directory (ADFS). لمزيد من المعلومات، راجع دعم ADFS.

ADAL NET MSAL NET
حزم NuGet ومساحات الأسماء تم استهلاك ADAL من حزمة NuGet Microsoft.IdentityModel.Clients.ActiveDirectory. كانت مساحة الاسم Microsoft.IdentityModel.Clients.ActiveDirectory. إضافة حزمة NuGet Microsoft.Identity.Client، واستخدام مساحة الاسم Microsoft.Identity.Client. إذا كنت تقوم بإنشاء تطبيق عميل سري، تحقق من Microsoft.Identity.Web.
النطاقات والموارد تحصل ADAL.NET على رموز مميزة للموارد. تحصل MSAL.NET على رموز مميزة للنطاقات. تتطلب عدة موانع لـ MSAL.NET AcquireTokenXXX معلمة تسمى النطاقات(IEnumerable<string> scopes). هذه المعلمة عبارة عن قائمة مكونة من سلاسل تقوم بالإعلان عن الأذونات والموارد المطلوبة. النطاقات المعروفة هي نطاقات Microsoft Graph. يمكنك أيضاً الوصول إلى موارد v1.0 باستخدام MSAL.NET.
الفئات الأساسية استخدامت ADAL.NET AuthenticationContext كتمثيل للاتصال الخاص بك إلى خدمة security token (STS) أو خادم التخويل، من خلال مخول. تم تصميم MSAL.NET حول تطبيقات العميل. وهو يعرف IPublicClientApplication واجهات لتطبيقات العملاء العامة وIConfidentialClientApplication لتطبيقات العملاء السرية، فضلا عن واجهة IClientApplicationBase الأساسية للاتفاق المشترك بين كلا النوعين من التطبيقات.
اكتساب الرمز المميز في العملاء العموميين، يستخدم ADAL AcquireTokenAsync وAcquireTokenSilentAsync لاستدعاءات المصادقة. في العملاء العموميين، يستخدم MSAL AcquireTokenInteractive وAcquireTokenSilent لنفس استدعاءات المصادقة. المعلمات مختلفة عن معلمات ADAL.

في تطبيقات العميل السرية، هناك أساليب لاقتناء الرمز المميز مع اسم صريح اعتمادا على السيناريو. والفرق الآخر هو أنه في MSAL.NET، لم تعد مضطراً لتمرير ClientID من تطبيقاتك في كل استدعاء AcquireTokenXX. يتم تعيين ClientID مرة واحدة فقط عند البناء أو IPublicClientApplication أو IConfidentialClientApplication .
IAccount وIUser يعرف ADAL مفهوم المستخدم من خلال واجهة IUser. ومع ذلك، المستخدم هو عامل بشري أو برنامج. على هذا النحو، يمكن للمستخدم امتلاك حساب واحد أو أكثر في النظام الأساسي للهوية في Microsoft (العديد من حسابات AAD (دليل Azure النشط)، متاجرة عمل-مستهلك AAD (دليل Azure النشط)، حسابات Microsoft الشخصية). يمكن للمستخدم أيضاً أن يكون مسؤولاً عن حساب واحد أو أكثر من حسابات النظام الأساسي للهوية في Microsoft. يعرف MSAL.NET مفهوم الحساب (من خلال واجهة IAccount). تقدم واجهة IAccount معلومات حول حساب واحد. يمكن للمستخدم أن يكون له عدة حسابات في المستأجرين المختلفة. توفر MSAL.NET معلومات أفضل في سيناريوهات الضيف بسبب توفير معلومات الحساب المنزلي. يمكنك قراءة المزيد عنالاختلافات بين IUser وIAccount.
استمرار ذاكرة التخزين المؤقت تسمح لك ADAL.NET بتوسيع الفئة TokenCache لتنفيذ وظيفة المثابرة المطلوبة على الأنظمة الأساسية بدون تخزين آمن (.NET Framework و.NET core) باستخدام BeforeAccess، وBeforeWrite من الأساليب. للحصول على التفاصيل، راجع إنشاء تسلسل ذاكرة التخزين المؤقت للرمز المميز في ADAL.NET. تجعل MSAL.NET ذاكرة التخزين المؤقت للرمز المميز فئة مغلقة، ما يزيل القدرة على توسيعها. على هذا النحو، يجب أن يكون تطبيق استمرار ذاكرة التخزين المؤقت للرمز المميز في شكل فئة مساعدة تتفاعل مع ذاكرة التخزين المؤقت للرمز المميز المغلقة. يتم وصف هذا التفاعل في مقالة إنشاء تسلسل ذاكرة التخزين المؤقت للرمز المميز في MSAL.NET. إنشاء تسلسل لتطبيق عميل عام (انظر ذاكرة التخزين المؤقت للرمز المميز لتطبيق العميل العام)، يختلف عن تطبيق العميل السري (انظر ذاكرة التخزين المؤقت للرمز المميز لتطبيق ويب أو واجهة برمجة تطبيقات الويب).
التخويل المشترك يستخدم ADAL AAD (دليل Azure النشط) v1.0. https://login.microsoftonline.com/commonالتخويل في AAD (دليل Azure النشط) v1.0 (الذي يستخدمه ADAL) يسمح للمستخدمين تسجيل الدخول باستخدام أي حساب لمؤسسة AAD (دليل Azure النشط) (العمل أو المدرسة). لا يسمح AAD (دليل Azure النشط) v1.0 بتسجيل الدخول باستخدام حسابات Microsoft الشخصية. لمزيد من المعلومات، راجع التحقق من صحة التخويل في ADAL.NET. يستخدم MSAL AAD (دليل Azure النشط) v2.0. https://login.microsoftonline.com/common التخويل في AAD (دليل Azure النشط) v2.0 (الذي يستخدمه MSAL) يسمح للمستخدمين تسجيل الدخول مع أي حساب لمؤسسة AAD (دليل Azure النشط) (العمل أو المدرسة) أو مع حساب Microsoft الشخصي. لتقييد تسجيل الدخول باستخدام حسابات المؤسسة فقط (حساب العمل أو المدرسة) في MSAL، ستحتاج إلى استخدام https://login.microsoftonline.com/organizations نقطة النهاية. للحصول على التفاصيل، راجع authority المعلمة في تطبيق العميل العام.

المنح المدعومة

وفيما يلي ملخص يقارن بين المنح المدعومة من MSAL.NET وADAL.NET لكل من تطبيقات العملاء العامة والسرية.

تطبيقات العميل العامة

الصورة التالية تلخص بعض الاختلافات بين ADAL.NET وMSAL.NET لتطبيق عميل عام.

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

فيما يلي المنح المدعومة في ADAL.NET وMSAL.NET لتطبيقات سطح المكتب والجوال.

امنح MSAL.NET ADAL.NET
تفاعلي الحصول على الرموز بشكل تفاعلي في MSAL.NET Auth التفاعلي
مصادقة Windows المتكاملة مصادقة Windows المتكاملة المصادقة المتكاملة على Windows (Kerberos)
اسم المستخدم / كلمة المرور مصادقة اسم المستخدم وكلمة المرور الحصول على الرموز المميزة باستخدام اسم المستخدم وكلمة المرور
تدفق كود الجهاز تدفق كود الجهاز ملف تعريف الجهاز للأجهزة التي لا تعمل بمتصفحات الويب

تطبيقات العميل السرية

الصورة التالية تلخص بعض الاختلافات بين ADAL.NET وMSAL.NET لتطبيق عميل سري.

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

فيما يلي المنح المعتمدة في ADAL.NET، وMSAL.NET، وMicrosoft.Identity.Web لتطبيقات الويب وواجهات برمجة التطبيقات على الويب وتطبيقات الخفي.

نوع التطبيق امنح MSAL.NET ADAL.NET
تطبيق ويب، واجهة برمجة تطبيقات ويب، الخفي بيانات اعتماد العميل تدفق بيانات اعتماد العميل في MSAL.NET تدفق بيانات اعتماد العميل في ADAL.NET
API للويب نيابة عن نيابة عن في MSAL.NET استدعاءات خدمة لخدمة نيابة عن المستخدم مع ADAL.NET
تطبيق ويب رمز Auth الحصول على رموز مميزة باستخدام رموز التخويل على تطبيقات الويب باستخدام A MSAL.NET الحصول على رموز مميزة باستخدام رموز التخويل على تطبيقات الويب باستخدام ADAL.NET

الترحيل من ADAL 2.x مع رموز التحديث المميزة

في ADAL.NET v2. X، تم الكشف عن رموز التحديث المميزة مما يسمح لك بتطوير حلول حول استخدام هذه الرموز المميزة عن طريق التخزين المؤقت لها واستخدام AcquireTokenByRefreshToken الأساليب التي توفرها ADAL 2.x.

وقد استخدمت بعض هذه الحلول في سيناريوهات مثل:

  • خدمات طويلة الأمد تقوم بإجراءات بما في ذلك تحديث لوحات المعلومات للمستخدمين عندما لا يكون المستخدمون متصلين / قد سجلوا الدخول إلى التطبيق.
  • سيناريوهات WebFarm لتمكين العميل لإحضار رمز التحديث المميز إلى خدمة ويب (يتم التخزين المؤقت من جانب العميل، ملف تعريف الارتباط المشفر، وليس جانب الخادم).

لا يعرض MSAL.NET رموز التحديث المميزة لأسباب أمنية. يعالج MSAL تحديث الرموز المميزة نيابة عنك.

لحسن الحظ، MSAL.NET لديه واجهة برمجة التطبيقات التي تسمح لك بترحيل رموز التحديث المميزة السابقة (المكتسبة مع ADAL) إلى 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);

باستخدام هذا الأسلوب، يمكنك توفير رمز التحديث المستخدم مسبقا مع أي نطاقات (موارد) تريدها. سيتم استبدال الرمز المميز للتحديث بآخر جديد وتخزينه مؤقتاً في التطبيق الخاص بك.

ونظراً لأن هذا الأسلوب مُعد للسيناريوهات التي ليست نموذجية، فإنه لا يمكن الوصول إليها بسهولة باستخدام IConfidentialClientApplication دون تخزينها مؤقتاً في IByRefreshToken.

يظهر القصاصة البرمجية التالية بعض التعليمات البرمجية للترحيل في تطبيق عميل سري.

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 لاسترداد الرمز المميز للتحديث الذي تم تخزينه في بعض وحدات التخزين بواسطة إصدار سابق من التطبيق الذي كان يستخدم ADAL 2.x. GetTokenCacheForSignedInUser إلغاء تسلسل ذاكرة التخزين المؤقت للمستخدم الذي تم تسجيل دخوله (لأن تطبيقات العميل السرية ينبغي أن تحتوي على ذاكرة تخزين مؤقت لكل مستخدم).

يتم إرجاع الرمز المميز للوصول والرمز الرمز المميز للمعرف في القيمة AuthenticationResult أثناء تخزين الرمز المميز للتحديث الجديد في ذاكرة التخزين المؤقت. يمكنك أيضاً استخدام هذا الأسلوب لسيناريوهات التكامل المختلفة عندما يتوفر لديك رمز تحديث مميز.

v1.0 والرموز v2.0

يوجد إصداران من الرموز المميزة: رموز v1.0 ورموز v2.0 المميزة. نقطة النهاية v1.0 (التي تستخدمها ADAL) تنبعث منها رموز المعرف المميزة v1.0 بينما نقطة النهاية v2.0 (التي تستخدمها MSAL) تنبعث منها رموز المعرف المميزة v2.0. ومع ذلك، كلتا نقطتي النهاية تنبعث منها رموز الوصول المميزة من إصدار الرمز المميز الذي تقبله واجهة برمجة تطبيقات الويب. خاصية من بيان التطبيق من واجهة برمجة التطبيقات على شبكة الإنترنت تمكن المطورين لاختيار أي إصدار من الرمز المميز هو مقبول. راجع accessTokenAcceptedVersion في وثائق مرجع بيان التطبيق.

لمزيد من المعلومات حول الرموز المميزة للوصول v1.0 وv2.0، راجع الرموز المميزة للوصول AAD (دليل Azure النشط).

استثناءات

تطلب التفاعل استثناءات

باستخدام MSAL.NET، يمكنك التقاط MsalUiRequiredException كما هو موضح في AcquireTokenSilent.

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

للحصول على التفاصيل، راجع معالجة الأخطاء والاستثناءات في MSAL.NET

ADAL.NET استثناءاتها أقل وضوحاً. على سبيل المثال، عند فشل المصادقة الصامتة في ADAL، فقد كان الإجراء هو التقاط الاستثناء والبحث عن user_interaction_required رمز الخطأ:

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

للحصول على تفاصيل، راجع النمط المستحسن للحصول على رمز مميز في تطبيقات العميل العامة مع ADAL.NET.

سلوك فوري

السلوك المطالب في MSAL.NET مكافئ للسلوك المطالب في ADAL.NET:

ADAL.NET MSAL.NET الوصف
PromptBehavior.Auto NoPrompt يختار AAD (دليل Azure النشط) أفضل سلوك (تسجيل الدخول للمستخدمين بصمت إذا تم تسجيل الدخول باستخدام حساب واحد فقط، أو عرض محدد الحساب إذا تم تسجيل الدخول باستخدام عدة حسابات).
PromptBehavior.Always ForceLogin يعيد تعيين مربع تسجيل الدخول ويفرض على المستخدم إعادة إدخال بيانات الاعتماد الخاصة بهم.
PromptBehavior.RefreshSession Consent يجبر المستخدم على الموافقة مرة أخرى على جميع الأذونات.
PromptBehavior.Never Never لا تستخدم؛ وبدلاً من ذلك، استخدم النمط الموصى به لتطبيقات العميل العامة.
PromptBehavior.SelectAccount SelectAccount يعرض محدد الحساب ويجبر المستخدم على تحديد حساب.

معالجة استثناءات الطعن في المطالبة

في بعض الأحيان عند الحصول على رمز مميز، يقوم AAD (دليل Azure النشط) بطرح استثناء في حالة طلب مورد مطالبات أكثر من المستخدم (على سبيل المثال المصادقة الثنائية).

وفي MSAL.NET، تعالج استثناءات الطعن في المطالبة على النحو التالي:

  • Claimsظهرت في MsalServiceException.
  • هناك طريقة .WithClaim(claims) يمكن أن تنطبق على المنشئين AcquireTokenXXX.

للحصول على تفاصيل راجع التعامل مع MsalUiRequiredException.

وفي MSAL.NET، تم التعامل مع استثناءات الطعن في المطالبة على النحو التالي:

  • AdalClaimChallengeException هو استثناء (مشتق من AdalServiceException). يحتوي العضو Claims على جزء JSON مع المطالبات المتوقعة.
  • احتاج تطبيق العميل العام الذي يتلقى هذا الاستثناء لاستدعاء تجاوز AcquireTokenInteractive الذي له معلمة مطالبات. هذا التجاوز AcquireTokenInteractive لا يحاول حتى الاصطدام بذاكرة التخزين المؤقت لأنه ليس ضرورياً. والسبب هو أن الرمز المميز في ذاكرة التخزين المؤقت لا يحتوي على المطالبات الصحيحة (وإلا لما تم طرح AdalClaimChallengeException). على هذا النحو، ليست هناك حاجة للنظر في ذاكرة التخزين المؤقت. يمكن أن يتم تلقي ClaimChallengeException في WebAPI التي تقوم بـ OBO، ولكن يجب استدعاء AcquireTokenInteractive في تطبيق عميل عام يستدعي واجهة برمجة تطبيقات الويب هذه.

للحصول على التفاصيل، بما في ذلك النماذج انظر التعامل مع AdalClaimChallengeException.

النطاقات

يستخدم ADAL مفهوم الموارد مع سلسلة resourceId، ومع ذلك، يستخدم MSAL.NET النطاقات. فيما يلي المنطق الذي تستخدمه AAD (دليل Azure النشط):

  • بالنسبة لنقطة النهاية ADAL (v1.0) مع الرمز المميز للوصول v1.0 (الرمز الوحيد الممكن)، aud=resource.
  • بالنسبة إلى MSAL (نقطة النهاية v2.0) التي تطلب رمزا مميزا للوصول إلى مورد يقبل رموز v2.0، aud=resource.AppId.
  • بالنسبة إلى MSAL (نقطة النهاية v2.0) التي تطلب رمزا مميزا للوصول لمورد يقبل رمز وصول v1.0، يوزع AAD (دليل Azure النشط) الجمهور المطلوب من النطاق المطلوب. ويتم ذلك عن طريق أخذ كل شيء قبل الشرطة المائلة الأخيرة واستخدامه كمعرف للمورد. على هذا النحو، إذا كان https://database.windows.net يتوقع جمهور من https://database.windows.net/، فستحتاج إلى طلب نطاق من https://database.windows.net//.default (لاحظ الشرطة المزدوجة قبل ./الافتراضي). ويتضح ذلك من المثالين 1 و2 أدناه.

مثال 1

إذا كنت ترغب في الحصول على رموز مميزة لتطبيق يقبل الرموز المميزة v1.0 (على سبيل المثال واجهة برمجة التطبيقات Microsoft Graph، وهو https://graph.microsoft.com )، فستحتاج إلى إنشاء scopes بواسطة ربط أجزاء معرف المورد المطلوب بإذن OAuth2 المطلوب لهذا المورد.

على سبيل المثال، للوصول إلى اسم المستخدم عبر واجهة برمجة تطبيقات ويب v1.0 التي يكون معرف التطبيق URI الخاص بها ResourceId، فأنت تريد استخدام:

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

إذا كنت ترغب في القراءة والكتابة باستخدام MSAL.NET Azure Active Directory باستخدام واجهة برمجة تطبيقات Microsoft Graph (https://graph.microsoft.com/)، فيمكنك إنشاء قائمة بالنطاقات الواردة في القصاصة البرمجية أدناه:

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

مثال 2

إذا كان المورد ينتهي بمعرف '/'، ستحتاج إلى أن يكون لديك '/' مزدوج عند كتابة قيمة النطاق. على سبيل المثال، إذا كنت تريد كتابة النطاق المطابق واجهة برمجة التطبيقات Azure Resource Manager (https://management.core.windows.net/)، اطلب النطاق التالي (لاحظ الشرطتين المائلتين).

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

هذا لأن واجهة برمجة تطبيقات Resource Manager تتوقع شرطة مائلة في مطالبة جمهورها (aud)، ثم هناك شرطة مائلة لفصل اسم واجهة برمجة التطبيقات عن النطاق.

إذا كنت ترغب في الحصول على رمز مميز لجميع النطاقات الثابتة لتطبيق v1.0، فيمكنك إنشاء قائمة النطاقات الخاصة بك كما هو موضح في القصاصة البرمجية أدناه:

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

لتدفق بيانات اعتماد عميل، سيكون نطاق لتمرير أيضاً /.default. يبلغ هذا النطاق AAD (دليل Azure النشط): "بجميع أذونات مستوى التطبيق التي وافق عليها المسؤول في تسجيل التطبيق.

الخطوات التالية

لترحيل تطبيقاتك من ADAL إلى MSALلترحيل تطبيقات العميل السرية ADAL.NET لاستخدام MSAL.NET