تسجيل تطبيق

  • 12 دقائق

تسجيل التطبيق الخاص بك يؤسس علاقة ثقة بين التطبيق الخاص بك والنظام الأساسي لهوية Microsoft. الثقة أحادية الاتجاه: يثق تطبيقك بالنظام الأساسي لهوية Microsoft - وليس العكس.

  1. سجل الدخول إلى مركز إدارة Microsoft Entra باستخدام حساب المسؤول.

  2. افتح قائمة المدخل ثم حدد Identity.

  3. في قائمة Identity ، ضمن Applications، حدد App registrations.

  4. في الصفحة "App registrations"، من القائمة، حدد "+ New registration".

  5. في مربع الحوار register an application، قم بتسجيل تطبيق يسمى Demo app باستخدام القيم الافتراضية. لا تحتاج إلى إدخال عنوان URI لإعادة التوجيه.

    لقطة شاشة تعرض شاشة «Register an application» مع تمييز الاسم والإعدادات الافتراضية.

  6. عند الاكتمال، سيتم توجيهك إلى شاشة Demo app.

إضافة إعادة توجيه URI

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

إضافة وتعديل عناوين URL لإعادة التوجيه للتطبيقات المسجلة عن طريق تكوين إعدادات النظام الأساسي.

تكوين إعدادات النظام الأساسي

يتم تكوين الإعدادات لكل نوع تطبيق، بما في ذلك عناوين URL لإعادة التوجيه، في "Platform configurations" في مدخل Azure. تتطلب بعض الأنظمة الأساسية، مثل تطبيقات Web وSingle-page، تحديد URI لإعادة التوجيه يدوياً. بالنسبة للأنظمة الأساسية الأخرى، مثل الجوال وسطح المكتب، يمكنك الاختيار من عناوين URL لإعادة التوجيه التي تم إنشاؤها لك عند تكوين إعداداتها الأخرى.

لتكوين إعدادات التطبيق استنادًا إلى النظام الأساسي أو الجهاز الذي تستهدفه:

  1. حدد التطبيق الخاص بك في "App registrations" في مدخل Azure.

  2. ضمن "Manage"، حدد "Authentication".

  3. ضمن "Platform configurations"، حدد "Add a platform".

  4. في "Configure platforms"، حدد تجانب نوع التطبيق (النظام الأساسي) لتكوين إعداداته.

    لقطة شاشة لجزء تكوين النظام الأساسي في مركز إدارة Microsoft Entra.

    النظام الأساسي إعدادات التكوين
    الويب أدخل Redirect URI من أجل تطبيقك، الموقع، حيث يقوم النظام الأساسي لهوية Microsoft بإعادة توجيه عميل مستخدم ويرسل رموز الأمان المميزة بعد المصادقة. حدد هذا النظام الأساسي لتطبيقات الويب القياسية التي تعمل على خادم.
    تطبيق صفحة واحدة أدخل Redirect URI من أجل تطبيقك، الموقع، حيث يقوم النظام الأساسي لهوية Microsoft بإعادة توجيه عميل مستخدم ويرسل رموز الأمان المميزة بعد المصادقة. حدد هذا النظام الأساسي إذا كنت تنشئ تطبيق ويب من جانب العميل باستخدام JavaScript أو إطار عمل مثل Angular أو Vue.js أو React.js أو Blazor WebAssembly.
    iOS/macOS أدخل Bundle ID للتطبيق، الموجود في XCode في Info.plist أو إعدادات الإنشاء. يتم إنشاء URI لإعادة التوجيه لك عند تحديد Bundle ID.
    Android أدخل Package name للتطبيق، والذي يمكنك العثور عليه في ملف AndroidManifest.xml، ثم قم بإنشاء Signature hash وأدخلها. يتم إنشاء URI لإعادة التوجيه لك عند تحديد هذه الإعدادات.
    تطبيقات الجوال وسطح المكتب حدد أحد عناوين URI لإعادة التوجيه المقترحة أو حدد عنوان URI لإعادة التوجيه المخصص. وبالنسبة لتطبيقات سطح المكتب، نوصي بما يلي:https://login.microsoftonline.com/common/oauth2/nativeclient حدد هذا النظام الأساسي لتطبيقات الجوال التي لا تستخدم أحدث مكتبة مصادقة Microsoft (MSAL) أو لا تستخدم وسيطاً. أيضًا حدد هذا النظام الأساسي لتطبيقات سطح المكتب.

  5. حدد "Configure" لإكمال تكوين النظام الأساسي.

إضافة بيانات اعتماد

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

يمكنك إضافة كل من الشهادات والبيانات السرية للعميل (سلسلة) كوثائق اعتماد إلى تسجيل تطبيق العميل السري.

لقطة شاشة لمدخل Azure تعرض جزء

إضافة شهادة

تسمى أحياناً مفتاح عام، وتُعد الشهادات هي نوع بيانات الاعتماد الموصى به، لأنها توفر مستوى أعلى من ضمان البيانات السرية للعميل. عند استخدام شهادة عامة موثوق بها، يمكنك إضافة الشهادة باستخدام ميزة "الشهادات والبيانات السرية". يجب أن تكون الشهادة أحد أنواع الملفات التالية: .cer، .pem، .crt.

إضافة سر عميل

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

  1. حدد التطبيق الخاص بك في "App registrations" في مدخل Azure.
  2. حدد Certificates and secrets، ثم حدد New client secret.
  3. إضافة وصف لسر العميل الخاص بك.
  4. حدد مدة.
  5. حدد إضافة.
  6. سجل القيم السرية للاستخدام في التعليمات البرمجية لتطبيق العميل؛ لن يتم عرضها مرة أخرى بعد مغادرة هذه الصفحة.

تسجيل واجهة برمجة تطبيقات الويب

لتوفير الوصول إلى الموارد في واجهة برمجة تطبيقات الويب، يجب أولاً تسجيل واجهة برمجة التطبيقات باستخدام النظام الأساسي لـ Microsoft.

  1. تنفيذ الخطوات أعلاه.
  2. تخطى أقسام "Add a redirect URI" و"Configure platform settings". لا تحتاج إلى تكوين URI لإعادة التوجيه لواجهة برمجة تطبيقات ويب حيث لم يتم تسجيل دخول أي مستخدم بشكل تفاعلي.
  3. تخطي قسم "Add credentials" الآن. فقط إذا كان وصول واجهة برمجة التطبيقات بمثابة واجهة برمجة التطبيقات لانتقال البيانات من الخادم فستحتاج بيانات الاعتماد الخاصة بها—وهو سيناريو غير مشمول في هذه المقالة.

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

إضافة نطاق

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

أولاً، اتبع الخطوات التالية لإنشاء نطاق مثال يسمى Employees.Read.All:

  1. قم بتسجيل الدخول إلى بوابة Azure.

  2. إذا كان لديك حق الوصول إلى العديد من المستأجرين، فاستخدم عامل تصفية "Directory + subscription" في القائمة العلوية لتحديد المستأجر الذي يحتوي على تسجيل تطبيق العميل.

  3. حدد Microsoft Entra ID، ثم App registrations، ثم حدد تسجيل تطبيق API الخاص بك.

  4. حدد Expose an API، ثم Add a scope.

    لقطة شاشة لجزء كشف واجهة برمجة التطبيقات لتسجيل التطبيق في مركز إدارة Microsoft Entra.

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

  6. بعد ذلك، حدد سمات النطاق في جزء Add a scope. لهذا الجولة، يمكنك استخدام قيم المثال أو تحديد قيم خاصة بك.

    ميدان الوصف مثال
    اسم النطاق اسم النطاق الخاص بك. اصطلاح تسمية النطاق الشائع هو resource.operation.constraint. Employees.Read.All
    من يمكنه الموافقة يختار المسؤول ما إذا يمكن قبول هذا النطاق من قبل المستخدمين أو إذا كانت موافقة المسؤول مطلوبة. حدد Admins only للحصول على أذونات ذات امتيازات أعلى. المسؤولون والمستخدمون
    اسم معرض لموافقة المسؤول وصف مختصر للغرض من النطاق الذي سيشاهده المسؤولون فقط. الوصول للقراءة فقط إلى سجلات الموظفين
    وصف موافقة المسؤول وصف أكثر تفصيلاً للإذن الممنوح من قبل النطاق الذي سيشاهده المسؤولون فقط. السماح للتطبيق بالوصول للقراءة فقط إلى كافة بيانات الموظف.
    اسم معرض لموافقة المستخدم وصف مختصر للغرض من النطاق. يتم عرضه للمستخدمين فقط إذا قمت بتعيين من يمكنه الموافقة على المسؤولين والمستخدمين. الوصول للقراءة فقط إلى سجلات الموظفين
    وصف موافقة المستخدم وصف أكثر تفصيلاً للإذن الممنوح من قبل النطاق. يتم عرضه للمستخدمين فقط إذا قمت بتعيين من يمكنه الموافقة على المسؤولين والمستخدمين. السماح للتطبيق بالوصول للقراءة فقط إلى بيانات الموظف.

  7. قم بتعيين "State" إلى "Enabled"، ثم حدد "Add scope".

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

    1. ضمن "Authorized client applications"، حدد "Add a client application."
    2. أدخل Application (client) ID لتطبيق العميل الذي تريد إجراء تخويل مسبق له. على سبيل المثال، أحد تطبيقات الويب الذي قمت بتسجيله مسبقًا.
    3. ضمن "Authorized scopes"، حدد النطاقات التي تريد منع المطالبة بالموافقة عليها، ثم حدد "Add application".
    4. إذا اتبعت هذه الخطوة الاختيارية، أصبح تطبيق العميل الآن تطبيقًا عميلاً معتمدًا مسبقًا (PCA)، ولن تتم مطالبة المستخدمين بموافقتهم عند تسجيل الدخول إليه.

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

لإضافة نطاق مثال Employees.Write.All، اتبع الخطوات أعلاه وحدد هذه القيم في جزء "Add a scope":

ميدان قيمة المثال
اسم النطاق Employees.Write.All
من يمكنه الموافقة المسؤولون فقط
اسم معرض لموافقة المسؤول حق الوصول لكتابة سجلات الموظفين
وصف موافقة المسؤول السماح للتطبيق بالوصول للكتابة إلى كافة بيانات الموظف.
اسم معرض لموافقة المستخدم بلا (اتركها فارغة)
وصف موافقة المستخدم بلا (اتركها فارغة)

تحقق من النطاقات المكشوفة

إذا قمت بإضافة كلا نطاقي الأمثلة الموضحين في الأقسام السابقة بنجاح، فسيظهران في عرض جزء "Expose an API" الخاص بتسجيل تطبيق واجهة برمجة التطبيقات للويب، على غرار هذه الصورة:

لقطة شاشة لجزء «Expose an API» يعرض نطاقين مكشوفين للتعيين في تسجيل التطبيق.

كما هو موضح في الصورة، السلسلة الكاملة للنطاق هي تسلسل من Application ID URI لواجهة برمجة تطبيقات الويب الخاصة بك وScope name للنطاق.

على سبيل المثال، إذا كان معرف التطبيق الخاص بواجهة برمجة التطبيقات على الويب الخاص بك هو https://contoso.com/api واسم النطاق Employees.Read.All، فإن النطاق الكامل هو:

https://contoso.com/api/Employees.Read.All

استخدام النطاقات المكشوفة

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

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

يمكنك عرض نطاقات إضافية لاحقًا حسب الضرورة. خذ بعين الاعتبار أن واجهة برمجة تطبيقات الويب الخاصة بك يمكن أن تعرض نطاقات متعددة مقترنة بالعديد من العمليات. يمكن أن يتحكم المورد الخاص بك في الوصول إلى واجهة برمجة تطبيقات الويب في وقت التشغيل عن طريق تقييم المطالبة (scp) للنطاق في الرمز المميز للوصول لـ OAuth 2.0 الذي يتلقاه.

ما يجري وراء الكواليس

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