استدعاء واجهة برمجة تطبيقات في نموذج Node.js تطبيق خفي

تستخدم هذه المقالة عينة Node.js تطبيق خفي لإظهار كيفية حصول تطبيق خفي على رمز مميز لاستدعاء واجهة برمجة تطبيقات الويب. يحمي معرف Microsoft Entra للعملاء واجهة برمجة تطبيقات الويب.

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

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

المتطلبات الأساسية

• ⁧⁩Node.js⁧⁩.

• .NET 7.0 أو أحدث.

• Visual Studio Code أو أي محرر تعليمات برمجية آخر.

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

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

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

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

1. سجل الدخول إلى مركز إدارة Microsoft Entraكمطور تطبيق على الأقل.

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

3. استعرض وصولا إلىتسجيلات> تطبيقتطبيقاتالهوية>.

4. حدد + New registration.

5. في صفحة Register an application التي تظهر، أدخل معلومات تسجيل التطبيق الخاص بك:

   1. في قسم Name، أدخل اسم تطبيق ذي معنى سيتم عرضه لمستخدمي التطبيق، على سبيل المثال ciam-ToDoList-api.

   2. لأنواع الحسابات المدعومة، حدد الحسابات في هذا الدليل التنظيمي فقط.

6. حدد Register لإنشاء التطبيق.

7. يتم عرض جزء نظرة عامة على التطبيق عند اكتمال التسجيل. سجل معرف الدليل (المستأجر)ومعرف التطبيق (العميل) لاستخدامه في التعليمات البرمجية المصدر للتطبيق الخاص بك.

تكوين أدوار التطبيق

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

1. من صفحة App registrations ، حدد التطبيق الذي قمت بإنشائه (مثل ciam-ToDoList-api) لفتح صفحة Overview الخاصة به.

2. ضمن إدارة، حدد أدوار التطبيق.

3. حدد Create app role، ثم أدخل القيم التالية، ثم حدد Apply لحفظ التغييرات:

   الخاصية	القيمة
   الاسم المعروض	ToDoList.Read.All
   أنواع الأعضاء المسموح بها	التطبيقات
   القيمة	ToDoList.Read.All
   الوصف	السماح للتطبيق بقراءة قائمة ToDo الخاصة بكل مستخدم باستخدام "TodoListApi"

4. حدد Create app role مرة أخرى، ثم أدخل القيم التالية لدور التطبيق الثاني، ثم حدد Apply لحفظ التغييرات:

   الخاصية	القيمة
   الاسم المعروض	ToDoList.ReadWrite.All
   أنواع الأعضاء المسموح بها	التطبيقات
   القيمة	ToDoList.ReadWrite.All
   الوصف	السماح للتطبيق بقراءة وكتابة قائمة ToDo الخاصة بكل مستخدم باستخدام "ToDoListApi"

تكوين المطالبات الاختيارية

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

استخدم الخطوات التالية لتكوين مطالبة idtyp الاختيارية:

1. ضمن ⁧⁩إدارة⁧⁩، حدد ⁧⁩تكوين الرمز المميز⁧⁩.

2. اختر إضافة مطالبة اختيارية.

3. ضمن نوع الرمز المميز، اختر Access.

4. حدد idtyp المطالبة الاختيارية.

5. حدد إضافة لحفظ التغييرات.

تسجيل تطبيق البرنامج الخفي

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

توضح لك الخطوات التالية كيفية تسجيل تطبيقك في مركز إدارة Microsoft Entra:

1. سجل الدخول إلى مركز إدارة Microsoft Entraكمطور تطبيق على الأقل.

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

3. استعرض وصولا إلىتسجيلات> تطبيقتطبيقاتالهوية>.

4. حدد + New registration.

5. في صفحة تسجيل تطبيق التي تظهر؛

   1. أدخل اسم تطبيق ذي معنى يتم عرضه لمستخدمي التطبيق، على سبيل المثال ciam-client-app.
   2. لأنواع الحسابات المدعومة، حدد الحسابات في هذا الدليل التنظيمي فقط.

6. اختر ⁧تسجيل⁧.

7. يعرض جزء نظرة عامة على التطبيق عند التسجيل الناجح. سجل معرف التطبيق (العميل) لاستخدامه في التعليمات البرمجية المصدر للتطبيق الخاص بك.

إنشاء سر عميل

قم بإنشاء سر عميل للتطبيق المسجل. يستخدم التطبيق سر العميل لإثبات هويته عندما يطلب الرموز المميزة.

1. من صفحة App registrations ، حدد التطبيق الذي قمت بإنشائه (مثل ciam-client-app) لفتح صفحة Overview الخاصة به.
2. ضمن إدارة، حدد الشهادات&الأسرار.
3. حدد New client secret.
4. في مربع الوصف ، أدخل وصفا لسر العميل (على سبيل المثال، سر عميل تطبيق ciam).
5. ضمن انتهاء الصلاحية، حدد المدة التي يكون فيها السر صالحا (وفقا لقواعد أمان المؤسسات)، ثم حدد إضافة.
6. سجّل قيمةالسر. ستستخدم هذه القيمة للتكوين في خطوة لاحقة.

ملاحظة

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

منح أذونات واجهة برمجة التطبيقات لتطبيق البرنامج الخفي

1. من صفحة App registrations ، حدد التطبيق الذي قمت بإنشائه، مثل ciam-client-app.

2. ضمن ⁧⁩Manage⁧⁩، حدد ⁧⁩API permissions⁧⁩.

3. ضمن أذونات مكونة، حدد إضافة إذن.

4. حدد علامة التبويب واجهات برمجة التطبيقات الخاصة بي.

5. في قائمة واجهات برمجة التطبيقات، حدد واجهة برمجة التطبيقات مثل ciam-ToDoList-api.

6. حدد خيار أذونات التطبيق . نحدد هذا الخيار حيث يقوم التطبيق بتسجيل الدخول بنفسه، وليس للمستخدمين.

7. من قائمة الأذونات، حدد TodoList.Read.All، ToDoList.ReadWrite.All (استخدم مربع البحث إذا لزم الأمر).

8. حدد الزر ⁧⁩Add permissions⁧⁩.

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

   1. حدد منح موافقة المسؤول لاسم <>المستأجر الخاص بك، ثم حدد نعم.
   2. حدد تحديث، ثم تحقق من ظهور Granted لاسم <>المستأجر الخاص بك ضمن Status لكلا الإذنين.

استنساخ نموذج التطبيق الخفي وواجهة برمجة تطبيقات الويب أو تنزيلها

للحصول على نموذج التعليمات البرمجية لتطبيق الويب، يمكنك القيام بأي من المهام التالية:

• قم بتنزيل ملف .zip أو استنساخ نموذج تطبيق الويب من GitHub عن طريق تشغيل الأمر التالي:

      git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
  

إذا اخترت تنزيل ملف .zip ، فاستخرج نموذج ملف التطبيق إلى مجلد حيث يبلغ الطول الإجمالي للمسار 260 حرفا أو أقل.

تثبيت تبعيات المشروع

1. افتح نافذة وحدة التحكم، وقم بالتغيير إلى الدليل الذي يحتوي على نموذج التطبيق Node.js:

       cd 2-Authorization\3-call-api-node-daemon\App
   

2. قم بتشغيل الأوامر التالية لتثبيت تبعيات التطبيق:

       npm install && npm update
   

تكوين نموذج التطبيق الخفي وواجهة برمجة التطبيقات

لاستخدام تسجيل التطبيق الخاص بك في نموذج تطبيق الويب للعميل:

1. في محرر التعليمات البرمجية، افتح App\authConfig.js الملف.

2. ابحث عن العنصر النائب:

   • Enter_the_Application_Id_Here واستبدله بمعرف التطبيق (العميل) للتطبيق الخفي الذي سجلته سابقا.

   • Enter_the_Tenant_Subdomain_Here واستبدله بالمجال الفرعي للدليل (المستأجر). على سبيل المثال، إذا كان المجال الأساسي للمستأجر الخاص بك هو contoso.onmicrosoft.com، فاستخدم contoso. إذا لم يكن لديك اسم المستأجر الخاص بك، فتعرف على كيفية قراءة تفاصيل المستأجر.

   • Enter_the_Client_Secret_Here واستبدله بالقيمة السرية لتطبيق الخفي التي نسختها سابقا.

   • Enter_the_Web_Api_Application_Id_Here واستبدله بمعرف التطبيق (العميل) لواجهة برمجة تطبيقات الويب التي نسختها سابقا.

لاستخدام تسجيل تطبيقك في نموذج واجهة برمجة تطبيقات الويب:

1. في محرر التعليمات البرمجية، افتح API\ToDoListAPI\appsettings.json الملف.

2. ابحث عن العنصر النائب:

   • Enter_the_Application_Id_Here واستبدله بمعرف التطبيق (العميل) لواجهة برمجة تطبيقات الويب التي نسختها.

   • Enter_the_Tenant_Id_Here واستبدله بمعرف الدليل (المستأجر) الذي نسخته سابقا.

   • Enter_the_Tenant_Subdomain_Here واستبدله بالمجال الفرعي للدليل (المستأجر). على سبيل المثال، إذا كان المجال الأساسي للمستأجر الخاص بك هو contoso.onmicrosoft.com، فاستخدم contoso. إذا لم يكن لديك اسم المستأجر الخاص بك، فتعرف على كيفية قراءة تفاصيل المستأجر.

تشغيل نموذج التطبيق الخفي واختباره وواجهة برمجة التطبيقات

1. افتح نافذة وحدة تحكم، ثم قم بتشغيل واجهة برمجة تطبيقات الويب باستخدام الأوامر التالية:

   cd 2-Authorization\3-call-api-node-daemon\API\ToDoListAPI
   dotnet run
   

2. قم بتشغيل عميل تطبيق الويب باستخدام الأوامر التالية:

       2-Authorization\3-call-api-node-daemon\App
        node . --op getToDos
   

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

{
    id: 1,
    owner: '3e8....-db63-43a2-a767-5d7db...',
    description: 'Pick up grocery'
},
{
    id: 2,
    owner: 'c3cc....-c4ec-4531-a197-cb919ed.....',
    description: 'Finish invoice report'
},
{
    id: 3,
    owner: 'a35e....-3b8a-4632-8c4f-ffb840d.....',
    description: 'Water plants'
}

كيف تعمل هذه الميزة

يستخدم تطبيق Node.js منحة بيانات اعتماد عميل OAuth 2.0 للحصول على رمز مميز للوصول لنفسه وليس للمستخدم. يحتوي الرمز المميز للوصول الذي يطلبه التطبيق على الأذونات الممثلة كأدوار. يستخدم تدفق بيانات اعتماد العميل هذه المجموعة من الأذونات بدلا من نطاقات المستخدم للرمز المميزة للتطبيق. لقد عرضت أذونات التطبيق هذه في واجهة برمجة تطبيقات الويب في وقت سابق، ثم منحتها لتطبيق البرنامج الخفي.

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

الوصول إلى البيانات

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

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

• تعرف على كيفية الحصول على رمز مميز للوصول، ثم استدعاء واجهة برمجة تطبيقات الويب في تطبيق Node.js الخفي الخاص بك.

• تعرف على كيفية استخدام شهادة العميل بدلا من سر للمصادقة في تطبيقك السري Node.js.

• تعرف على الأذونات والموافقة.