الأذونات والموافقة في منصة للهويات في Microsoft

  • مقالة
  • قراءة خلال 23 دقائق

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

النطاقات والأذونات

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

فيما يلي بعض الأمثلة على الموارد التي تستضيفها Microsoft على الويب:

  • Microsoft Graph: https://graph.microsoft.com
  • Microsoft 365 Mail API: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

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

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

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

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

في OAuth 2.0، تسمى أنواع هذه الأنواع من مجموعات الأذونات النطاقات. كما أنها غالباً يشار إليها باسم أذونات وصول. يتم تمثيل الإذن في النظام الأساسي لهوية Microsoft كقيمة سلسلة. يطلب التطبيق الأذونات التي يحتاجها عن طريق تحديد الإذن في scope معلمة الاستعلام. يدعم النظام الأساسي للهوية العديد من نطاقات OpenID Connect المعرفة جيدا بالإضافة إلى الأذونات المستندة إلى الموارد (يشار إلى كل إذن بإلحاق قيمة الإذن بمعرف المورد أو معرف التطبيق URI). على سبيل المثال، تُستخدم سلسلة الإذن https://graph.microsoft.com/Calendars.Read لطلب إذن قراءة التقويمات الخاصة بالمستخدم في Microsoft Graph.

التطبيق الأكثر شيوعًا يطلب هذه الأذونات عن طريق تحديد النطاقات في الطلبات إلى نقطة النهاية تخويل النظام الأساسي لهوية Microsoft. لكن، لا تُمنح الأذونات ذات الامتيازات العالية إلا بموافقة المسؤول. يمكن طلبها أو منحها باستخدام نقطة نهاية موافقة المسؤول. استمر في «القراءة» لتتعلم المزيد.

في طلبات التخويل أو الرمز المميز أو نقاط نهاية الموافقة لمنصة تعريف Microsoft، إذا تم حذف معرف المورد في معلمة النطاق، فمن المفترض أن يكون المورد هو Microsoft Graph. على سبيل المثال،scope=User.Readما يعادلhttps://graph.microsoft.com/User.Read.

أنواع الأذونات

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

  • يتم استخدام ⁧⁩Delegated permissions⁧⁩ من قبل التطبيقات التي لديها مستخدم مسجل الدخول حاليًا. بالنسبة لهذه التطبيقات، يوافق المستخدم أو المسؤول على الأذونات التي يطلبها التطبيق. يُفوض التطبيق بإذن للعمل كمستخدم قام بتسجيل الدخول عند إجراء مكالمات إلى مورد الهدف.

    يمكن الموافقة على بعض أذونات الوصول المفوضة من قبل غير المسؤولين. لكن بعض الأذونات ذات الامتيازات العالية تتطلب موافقة المسؤول. لمعرفة أدوار المسؤول التي يمكن أن توافق على الأذونات المفوضة، راجعأذونات دور المسؤول في Microsoft Azure Active Directory.

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

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

  • بالنسبة لأذونات الوصول المفوَّضة، فإنالأذونات الفعالةلتطبيقك هي التقاطع الأقل امتيازًا للأذونات المفوَّضة التي تمنح التطبيق (عن طريق الموافقة) وامتيازات المستخدم الذي قام بتسجيل الدخول حاليًا. لا يمكن أن يكون للتطبيق الخاص بك امتيازات أكثر من مستخدم مسجل الدخول.

    داخل المؤسسات، يمكن تحديد امتيازات المستخدم الذي قام بتسجيل الدخول من خلال النهج أو عن طريق العضوية في واحد أو أكثر من أدوار المسؤول. لمعرفة أدوار المسؤول التي يمكن أن توافق على الأذونات المفوضة، انظر أذونات دور المسؤول في Microsoft Azure Active Directory.

    على سبيل المثال، افترض أن التطبيق الخاص بك قد تم منحه إذن مفوض User.ReadWrite.All. يمنح هذا الإذن التطبيق بشكل اسمي قراءة الملف الشخصي لكل مستخدم في المؤسسة وتحديثه. إذا كان المستخدم الذي سجل الدخول مسؤولا عاما، يمكن للتطبيق الخاص بك تحديث ملف تعريف كل مستخدم في المؤسسة. ومع ذلك، إذا لم يكن للمستخدم الذي سجل الدخول دور مسؤول، يمكن للتطبيق تحديث ملف تعريف المستخدم الذي سجل الدخول فقط. لا يمكن تحديث ملفات تعريف المستخدمين الآخرين في المؤسسة لأن المستخدم الذي لديه إذن بالتصرف نيابة عنه لا يملك الامتيازات.

  • بالنسبة لأذونات الوصول للتطبيقات، تكون الأذونات الفعالةلتطبيقك هي المستوى الكامل للامتيازات التي يتضمنها الإذن. على سبيل المثال، يمكن للتطبيق الذي يحتوي على إذن التطبيق User.ReadWrite.All تحديث ملف تعريف كل مستخدم في المؤسسة.

مجموعات الاتصال OpenID

يحتوي تطبيق نظام هوية Microsoft الخاص بـ OpenID Connect على عدد قليل من النطاقات المحددة جيدًا والتي تتم استضافتها أيضًا على Microsoft Graph: openid،email،profileوoffline_access. لا يتم address دعم نطاقيphoneOpenID Connect.

إذا طلبت نطاقات OpenID Connect ورمزًا مميزًا، ستحصل على رمز مميز للاتصال بنقطة نهاية معلومات المستخدم.

المعرف الشخصي المفتوح

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

باستخدام هذا الإذن، يمكن أن يتلقى التطبيق معرّفًا فريدًا للمستخدم في شكلsub مطالبة. كما يمنح الإذن التطبيق حق الوصول إلى نقطة نهاية معلومات المستخدم. يمكنopenid استخدام النطاق في نقطة نهاية الرمز المميز لمنصة تعريف Microsoft للحصول على الرموز المميزة للمعرف. يستخدم التطبيق هذه الرموز المميزة للمصادقة.

البريد الإلكتروني

يمكنemailاستخدام النطاق مع openidالنطاق وأي مجالات أخرى. يمنح التطبيق حق الوصول إلى عنوان البريد الإلكتروني الأساسي للمستخدم في شكلemailالمطالبة.

تضمنemailالمطالبة في رمز مميز فقط إذا كان عنوان البريد الإلكتروني مرتبطًا بحساب المستخدم، وهو ما لا يحدث دائمًا. إذا كان تطبيقك يستخدم email النطاق، يجب أن يكون التطبيق قادرًا على التعامل مع حالة لا يوجد فيهاemailأي مطالبة في الرمز المميز.

ملف التعريف

يمكنprofileلاستخدام النطاق مع openidالنطاق وأي مجالات أخرى. يتيح التطبيق الوصول إلى كمية كبيرة من المعلومات حول المستخدم. تتضمن المعلومات التي يمكن الوصول إليها، على سبيل المثال لا الحصر، الاسم المحدد للمستخدم، واللقب، واسم المستخدم المفضل، ومعرف الكائن.

للحصول على القائمة كاملة profileبالمطالبات المتوفرة فيid_tokensالمعلمة لمستخدم معين، راجعid_tokensالمرجع.

offline_access

يمنح offline_accessالنطاقإلى التطبيق حق الوصول إلى الموارد نيابة عن المستخدم لفترة طويلة. يظهر هذا النطاق في صفحة الموافقة، ك "الاحتفاظ بالوصول إلى البيانات" التي منحتها حق الوصول إلىالإذن.

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

ملاحظة

يظهر هذا الإذن حاليًا على كافة صفحات الموافقة، حتى بالنسبة للمراجعات التي لا توفر رمز تحديث (مثلالمراجعة الضمنية). يعالج الإعداد سيناريوهات حيث يمكن أن يبدأ عميل ضمن المراجعة الضمنية ثم الانتقال إلى مراجعة التعليمات البرمجية حيث يتوقع رمز تحديث.

خلال نظام هوية Microsoft (الطلبات المقدمة إلى نقطة نهاية الإصدار 2.0)، يجب أن يطلب التطبيق الخاص بكoffline_accessالنطاق صراحةً لتلقي رموز التحديث. لذلك عندما تسترد رمز التفويض في مراجعة رمز مصادقة OAuth 2.0،ستتلقى رمز وصول فقط من/tokenنقطة النهاية.

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

للحصول على مزيد من المعلومات حول كيفية الحصول على رموز التحديث المميزة واستخدامها، راجع مرجع بروتوكول النظام الأساسي للهوية لـ Microsoft.

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

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

كما تمكن أذونات الوصول الثابتة المسؤولينمن الموافقة نيابة عن كافة المستخدمينفي المؤسسة.

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

  • يحتاج التطبيق إلى طلب جميع الأذونات التي سيحتاجها عند تسجيل الدخول الأول للمستخدم. قد يؤدي ذلك إلى قائمة طويلة من الأذونات التي تُثني المستخدمين النهائيين عن الموافقة على وصول التطبيق عند تسجيل الدخول الأولي.

  • يحتاج التطبيق إلى معرفة جميع الموارد التي يمكن الوصول إليها مسبقًا. من الصعب إنشاء تطبيقات يمكنها الوصول إلى عدد غير معلوم من الموارد.

باستخدام نقطة نهاية النظام الأساسي للهويات في Microsoft، يمكنك تجاهل الأذونات الثابتة المعرفة في معلومات تسجيل التطبيق في مدخل Microsoft Azure وطلب الأذونات بشكل متزايد بدلًا من ذلك. يمكنك طلب مجموعة الحد الأدنى من أذونات الوصول مقدما وطلب المزيد بمرور الوقت حيث يستخدم العميل ميزات تطبيق إضافية. للقيام بذلك، يمكنك تحديد النطاقات التي يحتاجها التطبيق الخاص بك في أي وقت من خلال تضمين النطاقات الجديدة فيscopeالمعلمة عند طلب رمز وصول- دون الحاجة إلى تعريفها مسبقًا في معلومات تسجيل التطبيق. إذا لم يوافق المستخدم بعد على النطاقات الجديدة التي تمت إضافتها إلى الطلب، فسيطلب منه الموافقة فقط على أذونات الوصول الجديدة. الموافقة المتزايدة أو الديناميكية، تنطبق فقط على أذونات الوصول المفوضة وليس على أذونات التطبيق.

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

هام

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

موافقة المسؤول - تكون مطلوبة عندما يحتاج التطبيق الخاص بك إلى الوصول إلى أذونات معينة عالية الامتياز. تضمن موافقة المسؤول أن يكون لدى المسؤولين بعض عناصر التحكم الإضافية قبل تفويض التطبيقات أو المستخدمين بالوصول إلى البيانات ذات الامتيازات العالية من المؤسسة.

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

فيطلب التخويل OpenID Connect أو OAuth 2.0 يمكن للتطبيق طلب الأذونات التي يحتاجها باستخدامscopeمعلمة الاستعلام. على سبيل المثال، عندما يقوم المستخدم بتسجيل الدخول إلى أحد التطبيقات، يرسل التطبيق طلبًا مثل المثال التالي. (تتم إضافة خط التقاطع للوضوح.)

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

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

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

في هذا الوقت، offline_accessيتم تضمين إذن ("الحفاظ على الوصول إلى البيانات التي منحتها حق الوصول إليها") والإذن User.Read("تسجيل الدخول وقراءة ملف التعريف الخاص بك") تلقائيًا في الموافقة الأولية للتطبيق. هذه الأذونات مطلوبة بشكل عام لدالة التطبيق المناسبة. يمنحoffline_access الإذن إلي التطبيق بالوصول إلى تحديث الرموز المميزة التي تعتبر ضرورية للتطبيقات الأصلية وتطبيقات الويب. وUser.Readيمنح الإذن حق الوصول إلىsubالمطالبة. يسمح للعميل أو التطبيق بتحديد هوية المستخدم بشكل صحيح بمرور الوقت والوصول إلى معلومات المستخدم الأولية.

Example screenshot that shows work account consent.

عندما يوافق المستخدم على طلب الإذن، تسجل الموافقة. لا يتعين على المستخدم الموافقة مرة أخرى عند تسجيل دخول لاحقًا إلى التطبيق.

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

تتطلب موافقة المسؤول التي تم إجراؤها نيابة عن مؤسسة أذونات الوصول الثابتة المسجلة للتطبيق. عيّن هذه الأذونات للتطبيقات في بوابة تسجيل التطبيق إذا كنت بحاجة إلى مسؤول لمنح الموافقة نيابة عن المؤسسة بأكملها.

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

بالإضافة إلى ذلك، يجب أن تستخدم التطبيقات نقطة نهاية موافقة المسؤول لطلب أذونات التطبيق.

أذونات مقيدة على المسؤول

يمكن تعيين بعض أذونات الامتياز العالي في موارد Microsoft علىتقييد المسؤول. فيما بعد بعض الأمثلة على هذه الأنواع من أذونات الوصول:

  • اقرأ «كل ملفات التعريف» الكاملة للمستخدمUser.Read.All
  • أكتب «البيانات» إلى دليل المؤسسة باستخدامDirectory.ReadWrite.All
  • اقرأ «جميع المجموعات» في دليل المؤسسة باستخدامGroups.Read.All

ملاحظة

في طلبات التخويل أو الرمز المميز أو موافقة النظام الأساسي ل Microsoft Identity، إذا تم حذف معرف المورد في معلمة النطاق، يفترض أن المورد هو Microsoft Graph. على سبيل المثال،scope=User.Readما يعادلhttps://graph.microsoft.com/User.Read.

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

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

إذا طلب التطبيق أذونات وصول مفوضة ذات امتيازات عالية ومنح المسؤول هذه الأذونات من خلال نقطة نهاية موافقة المشرف، يتم منح الموافقة لجميع المستخدمين في المستأجر.

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

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

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

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

لمراجعة نموذج تعليمات برمجية الذي يطبق الخطوات راجع نموذج نطاقات مقيدة من قبل المسؤول في GitHub.

طلب الأذونات في مدخل تسجيل التطبيق

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

بشكل عام، يجب تعريف أذونات الوصول بشكل ثابت لتطبيق معين. يجب أن تكون مجموعة شاملة من الأذونات التي سيطلبها التطبيق بشكل ديناميكي أو متزايد.

ملاحظة

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

لتكوين قائمة أذونات الوصول المطلوبة بشكل ثابت لتطبيق:

  1. انتقل إلى مدخل Microsoft Azure - تجربة بدء تشغيل السريعلتسجيلات التطبيقات.
  2. حدد «التطبيق»، أوأنشئ «التطبيق»إذا لم تكن قد قمت بذلك بالفعل.
  3. في صفحة نظرة عامة في التطبيق، ضمن إدارة، حدد أذونات API>إضافة إذن.
  4. حدد «Microsoft Graph» من قائمة APIs المتاحة. ثم أضف الأذونات التي يتطلبها التطبيق الخاص بك.
  5. انقر فوق إضافة أذونات.

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

  • جزء من مراجعة الاشتراك في التطبيق.
  • جزء من الإعدادات للتطبيق.
  • مراجعة مخصصة "للاتصال".

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

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

لتسجيل دخول المستخدم، اتبع ⁦⁩البرنامج التعليمي لبروتوكول النظام الأساسي للهويات في Microsoft⁦⁩.

طلب أذونات الوصول من مسؤول الدليل

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

// Line breaks are for legibility only.
GET https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&state=12345
&redirect_uri=http://localhost/myapp/permissions
&scope=
https://graph.microsoft.com/calendars.read
https://graph.microsoft.com/mail.send
المعلمة الشرط الوصف
tenant مطلوب مستأجر الدليل الذي تريد طلب إذن منه. يمكن توفيره بتنسيق GUID أو تنسيق اسم مألوف. أو يمكن الرجوع إليها بشكل عام مع المنظمات، كما هو موضح في المثال. لا تستخدم "عام"، لأن الحسابات الشخصية لا يمكنها تقديم موافقة المسؤول إلا في سياق المستأجر. لضمان أفضل توافق مع الحسابات الشخصية التي تدير المستأجرين، استخدم معرف المستأجر عندما يكون ذلك ممكنًا.
client_id مطلوب معرّف التطبيق (العميل) الذي تم تعيينه لتطبيق مدخل Microsoft Azure - تجربة تسجيلات التطبيق.
redirect_uri مطلوب URI لإعادة التوجيه حيث تريد إرسال الاستجابة إلى التطبيق للمعالجة. يجب أن تتطابق تمامًا واحدة من URI لإعادة التوجيه التي قمت بتسجيلها في مدخل تسجيل التطبيق.
state المستحسنة قيمة مضمّنة في الطلب سيتم إرجاعها أيضًا في استجابة الرمز المميز. يمكن أن تكون سلسلة من أي محتوى تريده. استخدم الحالة لترميز المعلومات حول حالة المستخدم في التطبيق قبل حدوث طلب المصادقة، مثل الصفحة أو العرض الذي كان عليه.
scope مطلوب تحديد مجموعة الأذونات التي يتم طلبها من التطبيق. يمكن أن تكون هذه نطاقات ثابتة (باستخدام⁧.default) أو ديناميكية. يمكن أن تتضمن هذه المجموعة نطاقات OpenID Connect (openid،profile، email). إذا كنت بحاجة إلى أذونات وصول التطبيق، يجب استخدام .defaultلطلب قائمة الأذونات المكونة بشكل ثابت.

عند هذه النقطة، يتطلب Azure AD مسؤول المستأجر تسجيل الدخول لإكمال الطلب. يُطلب من المسؤول الموافقة على جميع الأذونات التي طلبتها فيscope المعلمة. إذا استخدمت قيمة ثابتة (.default)، فستعمل مثل نقطة نهاية موافقة المسؤول v1.0 وتطلب الموافقة على جميع النطاقات الموجودة في الأذونات المطلوبة للتطبيق.

استجابة ناجحة

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

GET http://localhost/myapp/permissions?tenant=a8990e1f-ff32-408a-9f8e-78d3b9139b95&state=state=12345&admin_consent=True
المعلمة الوصف
tenant مستأجر الدليل الذي منح التطبيق الخاص بك أذونات الوصول التي طلبها بتنسيق GUID.
state قيمة مضمنة في الطلب التي سيتم إرجاعها أيضًا في استجابة الرمز المميز. يمكن أن تكون سلسلة من أي محتوى تريده. تُستخدم الحالة لتشفير المعلومات حول حالة المستخدم في التطبيق قبل حدوث طلب المصادقة، مثل الصفحة أو العرض الذي كانوا فيه.
admin_consent سيتم التعيين على⁦True⁩.

استجابة خطأ

إذا لم يوافق المسؤول على أذونات تطبيقك، فإن الاستجابة الفاشلة تبدو كما يلي:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
المعلمة الوصف
error سلسلة رمز الخطأ يمكن استخدامها لتصنيف أنواع الأخطاء التي تحدث. يمكن أيضًا استخدامه للرد على الأخطاء.
error_description رسالة الخطأ المعينة يمكن أن تساعد المطور في التعرف على السبب الجذري للخطأ.

بعد تلقي استجابة ناجحة من نقطة نهاية موافقة المسؤول، اكتسب تطبيقك الأذونات التي طلبها. بعد ذلك، يمكنك طلب رمز للمورد الذي تريده.

استخدام الأذونات

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

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "6731de76-14a6-49ae-97bc-6eba6914391e",
    "scope": "https://outlook.office.com/Mail.Read https://outlook.office.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "zc53fwe80980293klaj9823"  // NOTE: Only required for web apps
}

يمكنك استخدام رمز الوصول الناتج في طلبات HTTP إلى المورد. إنه يشير بشكل موثوق إلى المورد إلى أن التطبيق الخاص بك لديه الإذن المناسب للقيام بمهمة محددة.

لمزيد من المعلومات حول بروتوكول OAuth 2.0 وكيفية الحصول على رموز الوصول، راجع مرجع بروتوكول نقطة نهاية النظام الأساسي لهوية Microsoft.

النطاق الافتراضي

يتم استخدام النطاق .default للإشارة بشكل عام إلى خدمة مورد (API) في أي طلب، دون تحديد أذونات معينة. إذا كانت الموافقة ضرورية، فإن استخدام .default يشير إلى ضرورة طلب الموافقة لجميع الأذونات المطلوبة المدرجة في تسجيل التطبيق (لجميع واجهات برمجة التطبيقات في القائمة).

يتم إنشاء قيمة معلمة النطاق باستخدام معرف URI للمورد و.default، مفصولة بشرطة مائلة للأمام (/). على سبيل المثال، إذا كان معرف URI للمورد هو https://contoso.com، فإن النطاق المطلوب هو https://contoso.com/.default. بالنسبة للحالات التي يجب فيها تضمين شرطة مائلة ثانية لطلب الرمز المميز بشكل صحيح، راجعالقسم الخاص بالشرط المائلة اللاحقة.

إن استخدام scope={resource-identifier}/.default من الناحية الوظيفية هو نفسه resource={resource-identifier} في نقطة النهاية v1.0 (حيث {resource-identifier} هو معرف URI من أجل API، على سبيل المثال https://graph.microsoft.com من أجل Microsoft Graph).

يمكن استخدام النطاق .default في أي تدفق OAuth 2.0 ولبدء موافقة المسؤول. من الضروري الاستخدام في التدفق نيابة عن و تدفق بيانات اعتماد العميل.

لا يستطيع العملاء الجمع بين الموافقة الثابتة (.default) والموافقة الديناميكية في طلب واحد. لذلكscope=https://graph.microsoft.com/.default Mail.Readينشأ خطأ لأنه يجمع بين أنواع النطاق.

النطاق.defaultيتطابق وظيفيًا مع سلوك resourceنقطة النهاية v1.0 مركزية. يحمل سلوك الموافقة من نقطة النهاية v1.0 كذلك. أي، .default يؤدي إلى مطالبة موافقة فقط إذا لم يتم منح الموافقة على أي إذن مفوض بين العميل والمورد، نيابة عن المستخدم الذي قام بتسجيل الدخول.

إذا كانت الموافقة موجودة، يحتوي الرمز المميز الذي تم إرجاعه على كافة النطاقات الممنوحة لذلك المورد للمستخدم الذي قام بتسجيل الدخول. ومع ذلك، إذا لم يتم منح أي إذن للمورد الطالب (أو إذا تم توفير المعلمة prompt=consent)، يتم عرض مطالبة موافقة لكافة الأذونات المطلوبة المكونة على تسجيل تطبيق العميل لكافة واجهات برمجة التطبيقات في القائمة.

على سبيل المثال، إذا كان النطاق https://graph.microsoft.com/.default مطلوباً، فإن التطبيق لديك يطلب رمز مميز للوصول إلى Microsoft Graph API. إذا تم منح إذن مفوض واحد على الأقل من أجل Microsoft Graph نيابة عن المستخدم الذي قام بتسجيل الدخول، ستستمر عملية تسجيل الدخول وسيتم تضمين كافة الأذونات المفوضة من Microsoft Graph والتي تم منحها لذلك المستخدم في الرمز المميز للوصول. إذا لم يتم منح أية أذونات للمورد الطالب (Microsoft Graph، في هذا المثال)، فسيتم تقديم مطالبة موافقة لكافة الأذونات المطلوبة المكونة على التطبيق لكافة واجهات برمجة التطبيقات في القائمة.

مثال1: المستخدم، أو المسؤول المستأجر، منح الأذونات

في هذا المثال، منح المستخدم أو مسؤول المستأجر Mail.ReadأذوناتUser.Read Microsoft Graph للعميل.

إذا طلب العميلscope=https://graph.microsoft.com/.default، فلن يتم عرض مطالبة بالموافقة، بغض النظر عن محتويات الأذونات المسجلة لتطبيق العميل لـMicrosoft Graph. يحتوي الرمز المميز للوصول الذي تم إرجاعه على النطاقاتMail.ReadوUser.Read.

مثال 2: لم يمنح المستخدم أذونات الوصول بين العميل والمورد

في هذا المثال، لم يمنح المستخدم الموافقة بين العميل وMicrosoft Graph، وليس لديه مسؤول. قام العميل بالتسجيل للحصول على أذونات الوصولUser.ReadوContacts.Read. كما أنها سجلت لنطاق Azure Key Vaulthttps://vault.azure.net/user_impersonation.

عندما يطلب العميل رمزاً مميزاً من أجل scope=https://graph.microsoft.com/.default، يرى المستخدم صفحة موافقة من أجل نطاقات User.Read و Contacts.Read لـ Microsoft Graph، ومن أجل النطاق user_impersonation في Azure Key Vault. الرمز المميز الذي تم إرجاعه يحتوي على النطاقات User.Read و Contacts.Read فقط، ويمكن استخدامه فقط مقابل Microsoft Graph.

مثال 3: وافق المستخدم، ويطلب العميل المزيد من النطاقات

في هذا المثال، وافق المستخدم بالفعل Mail.Readعلى العميل. سجل العميل للحصول على أذونات الوصولContacts.Read.

يقوم العميل أولاً بتنفيذ تسجيل الدخول باستخدام scope=https://graph.microsoft.com/.default. استناداً إلى معلمة الاستجابة scopes، تكشف التعليمات البرمجية للتطبيق أن Mail.Read فقط تم منحه. من ثم يبدأ العميل عملية تسجيل دخول ثانية باستخدام scope=https://graph.microsoft.com/.default، وهذه المرة يفرض الموافقة باستخدام prompt=consent. إذا سمح للمستخدم بالموافقة على جميع الأذونات التي سجلها التطبيق، سيتم عرض مطالبة الموافقة. (إذا لم يكن الأمر كذلك، فستظهر لهم رسالة خطأ أو نموذج طلب موافقة المسؤول.) كل من Contacts.Read و Mail.Read سيكونا في مطالبة الموافقة. إذا تم منح الموافقة ويستمر تسجيل الدخول، فإن الرمز المميز الذي تم إرجاعه هو من أجل Microsoft Graph، ويحتوي على Mail.Read و Contacts.Read.

استخدام النطاق .الافتراضي مع العميل

في بعض الحالات، يمكن للعميل أن يطلب النطاق الخاص.defaultبه. يوضح المثال التالي السيناريو وهو.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=9ada6f8a-6d83-41bc-b169-a306c21527a5
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

ينتج عن مثال الرمز هذا صفحة موافقة لجميع الأذونات المسجلة إذا كانت الأوصاف السابقة للموافقة.defaultتنطبق على السيناريو. ثم بعد ذلك إرجاع التعليمات البرمجيةid_token، بدلًا من رمز وصول مميز.

يلائم هذا السلوك بعض العملاء القدامى الذين يتم نقلهم من مصادقة (ADAL)Microsoft Azure Active Directory إلي مكتبة مصادقة (MSAL) Microsoft. لاينبغي استخدام هذا الإعداد من قبل العملاء الجدد الذين يستهدفون نظام هوية Microsoft.

تمنح بيانات اعتماد العميل التدفق و .الافتراضي

استخدام آخر لـ .defaultهو طلب أدوار التطبيق (يعرف كذلك باسم أذونات التطبيق) في تطبيق غير تفاعلي مثل التطبيق الخفي الذي يستخدم بيانات اعتماد العميل التي تمنح التدفق لاستدعاء واجهة برمجة تطبيقات الويب.

لتحديد أدوار التطبيق (أذونات التطبيق) من أجل API الويب، راجع إضافة أدوار التطبيق في التطبيق الخاص بك.

يجب أن تتضمن طلبات بيانات اعتماد العميل في خدمة العميل لديك scope={resource}/.default. هنا، {resource} هو واجهة برمجة التطبيقات على الويب التي ينوي تطبيقك استدعائها، ويرغب في الحصول على رمز مميز للوصول لها. إصدار طلب بيانات اعتماد عميل باستخدام أذونات تطبيق فردية (أدوار)غيرمدعومة. يتم تضمين كافة أدوار التطبيق (أذونات التطبيق) التي تم منحها لواجهات برمجة التطبيقات على الويب هذه في الرمز المميز للوصول الذي تم إرجاعه.

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

الشرطة المائلة اللاحقة و .الافتراضي

تحتوي بعض محددات الموارد المنتظمة (URIs) على شرطة مائلة للأمام، على سبيل المثال،https://contoso.com/في مقابلhttps://contoso.com. يمكن أن تتسبب الشرطة المائلة اللاحقة في حدوث مشكلات في التحقق من صحة الرمز المميز. تحدث المشكلات بشكل أساسي عند طلب رمز مميز لـ Azure Resource Manager (https://management.azure.com/). في هذه الحالة، تعني الشرطة المائلة اللاحقة على URI المورد أن الخط المائل يجب أن يكون موجودًا عند طلب الرمز المميز. لذلك عندما تطلب رمزًا مميزًاhttps://management.azure.com/ وتستخدمه.default، يجب أن تطلبhttps://management.azure.com//.default (لاحظ الشرطة المائلة المزدوجة!). بشكل عام، إذا تحقق من أن يتم إصدار الرمز المميز، وإذا تم رفض الرمز المميز من قبل API التي يجب أن تقبله، يؤخذ في الاعتبار إضافة شرطة مائلة للأمام ثانية ثم محاولة مرة أخرى.

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

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