تخويل الوصول إلى APIs باستخدام Microsoft Authentication Library

  • 5 دقائق

يمكنك الآن تسجيل دخول المستخدمين في شركتك في تطبيق الويب. بعد ذلك، تريد عرض معلومات مثل المسمى الوظيفي والبريد الإلكتروني للعمل وما إلى ذلك من ملف تعريف الموظف على الصفحة. تجد أن Microsoft Graph API يوفر الوصول إلى البيانات المتعلقة بالمستخدم.

في هذه الوحدة، ستتعلم كيف يمكن أن تساعدك MSAL في الحصول على حق الوصول المصرح به إلى خدمات Microsoft مثل واجهة برمجة تطبيقات Microsoft Graph.

أذونات API ونطاقاتها

تحدد خدمات الويب التي يتم تأمينها بواسطة معرف Microsoft Entra مجموعة من الأذونات التي توفر الوصول إلى وظيفة واجهة برمجة التطبيقات والبيانات التي تعرضها الخدمة. يمكن لتطبيق طلب هذه الأذونات من المستخدمين والمسؤولين الذين يجب أن يوافقوا على الطلب قبل أن يتمكن التطبيق من الوصول إلى البيانات أو العمل نيابة عن المستخدم. على سبيل المثال، قدمتMicrosoft Graphتعريف أذونات للقيام بالمهام التالية، من بين مهام أخرى:

  • قراءة التقويم الخاص بالمستخدم
  • الكتابة في التقويم الخاص بالمستخدم
  • إرسال بريد كمستخدم

يمكن للمستخدمين والمسؤولين التحكم ومعرفة البيانات التي يمكن للتطبيق الوصول إليها. قبل أن يتمكن تطبيقك من الوصول إلى واجهة برمجة تطبيقات مؤمنة بواسطة Microsoft، تحتاج إلى توفير أذونات التطبيق لتنفيذ الإجراءات.

يدعم معرف Microsoft Entra نوعين من الأذونات: الأذونات المفوضة وأذونات التطبيق.

  • يتم استخدام الأذونات المفوضة من قِبل التطبيقات التي لديها مستخدم قام بتسجيل الدخول. بالنسبة لهذه التطبيقات، يوافق المستخدم أو المسؤول على الأذونات التي يطلبها التطبيق. تم تفويض التطبيق الإذن للعمل كمستخدم قام بتسجيل الدخول عند إجراء مكالمات إلى API الهدف. تتطلب بعض الأذونات ذات الامتيازات العالية موافقة المسؤول.

  • يتم استخدام Application permissions من قِبل التطبيقات التي تعمل دون وجود مستخدم قام بتسجيل الدخول؛ على سبيل المثال، التطبيقات التي يتم تشغيلها كخدمات خلفية أو برامج خفية. يمكنللمسؤول فقط الموافقة علىأذونات التطبيق.

يمكنك تعيين أذونات واجهة برمجة التطبيقات هذه لتسجيل التطبيق من مدخل Microsoft Azure.

النطاقات

يقوم Microsoft Entra ID بتنفيذ بروتوكول التخويل OAuth 2.0 الذي يمكن للتطبيق من خلاله الوصول إلى الموارد المستضافة على الويب نيابة عن مستخدم.

في OAuth 2.0، تسمى أنواع هذه الأنواع من مجموعات الأذونات النطاقات. عند تقديم طلب تخويل إلى معرف Microsoft Entra، يطلب أحد التطبيقات الأذونات التي يحتاجها عن طريق تحديد الإذن في معلمة الاستعلام الخاصة بالطلب scope . على سبيل المثال، يتم استخدام قيمة النطاق https://graph.microsoft.com/Calendars.Read لطلب الإذن لقراءة التقويمات الخاصة بالمستخدم في Microsoft Graph.

الحصول على الرموز المميزة للوصول باستخدام MSAL

تمكن الرموز المميزة للوصول تطبيقات العميل من استدعاء واجهات برمجة تطبيقات الويب المحمية بواسطة معرف Microsoft Entra بشكل آمن. هناك عدة طرق للحصول على رمز مميز للوصول باستخدام Microsoft Authentication Library (MSAL). بشكل عام، تعتمد الطريقة المستخدمة للحصول على رمز مميز على ما إذا كان التطبيق تطبيق عميل عام مثل جهاز سطح المكتب أو تطبيق الهاتف المحمول، أو تطبيق عميل سري مثل تطبيق الويب أو API على الويب أو تطبيق خفي.

تتطلب العديد من أساليب الحصول على الرمز المميز لـ MSAL scopes معلمة، وهي قائمة سلاسل تقوم بإعلان الأذونات المرجوة والموارد المطلوبة.

يقوم MSAL بتخزين رمز مميز مؤقتًا بعد الحصول عليه. بالنسبة إلى تطبيقات ويب التي تستخدم تدفق رمز التخويل OpenID Connect فالنمط الموصى به في وحدات التحكم هو:

  • حاول أولا الحصول على رمز مميز بصمت من ذاكرة التخزين المؤقت قبل محاولة الحصول على رمز مميز بوسائل أخرى. التعليمات البرمجية التالية هي مقتطف من acquireTokenSilently تنفيذ الأسلوب في AuthHelper الفئة .

    final SilentParameters parameters = SilentParameters
                                        .builder(Collections.singleton(Config.SCOPES), context.getAccount())
                                        .build();

final ConfidentialClientApplication client = getConfidentialClientInstance();

client.tokenCache().deserialize(context.getTokenCache());

final IAuthenticationResult result = client.acquireTokenSilently(parameters).get();

  • إذا لم يكن هناك رمز مميز في ذاكرة التخزين المؤقت وفشل طلب الرمز المميز الصامت في الحصول على رمز مميز، يمكنك الحصول على الرمز المميز باستخدام تدفق رمز التخويل:

    final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
                                                    .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES))
                                                    .build();

final IAuthenticationResult result = app.acquireToken(authParams).get();

MSAL أيضًا قادرًا على تحديث رمز مميز عند الاقتراب من انتهاء الصلاحية (كما تحتوي ذاكرة التخزين المؤقت للرمز المميز أيضًا على رمز مميز للتحديث).

نتائج المصادقة

عندما يطلب العميل رمزا مميزا للوصول، يقوم معرف Microsoft Entra أيضا بإرجاع نتيجة مصادقة تتضمن بيانات تعريف حول الرمز المميز للوصول. تسمح هذه البيانات لتطبيقك بالقيام بالتخزين المؤقت الذكي للرموز المميزة للوصول دون الحاجة إلى توزيع الرمز المميز للوصول نفسه. تعرض AuthenticationResult إرجاعات MSAL ما يلي:

  • الرمز المميز للوصول لـ API الويب.
  • الرمز المعرّف المميز معرف للمستخدم (JWT).
  • صلاحية الرمز المميز، الذي يوضح التاريخ/الوقت الذي تنتهي فيه صلاحية الرمز المميز.
  • يحتوي معرف المستأجر على المستأجر الذي تم العثور على المستخدم فيه.
  • النطاقات التي تم إصدار الرمز المميز لها.
  • معرِّف فريد للمستخدم.

مقدمة حول Microsoft Graph

توفر Microsoft Graph API نقطة نهاية واحدة، https://graph.microsoft.com، لتوفير الوصول إلى البيانات والتفاصيل الغنية التي تركز على الأشخاص في سحابة Microsoft. يمكنك استخدام REST APIs أو SDKs للوصول إلى نقطة النهاية وإنشاء تطبيقات تدعم سيناريوهات Microsoft 365، والتي تمتد عبر الإنتاجية والتعاون والتعليم والأشخاص وذكاء مكان العمل، وأكثر من ذلك بكثير. يتضمن Microsoft Graph أيضا مجموعة قوية من الخدمات التي تدير هوية المستخدم والجهاز.

على سبيل المثال، يمكنك قراءة خصائص مستخدم قام بتسجيل الدخول عن طريق الوصول إلى https://graph.microsoft.com/v1.0/me نقطة النهاية.