تكوين المصادقة في عينة تطبيق ويب Node.js باستخدام Azure Active Directory B2C

مقالة
11/08/2023

في هذه المقالة، ستتعرف على كيفية تكوين عينة تطبيق ويب Node.js لاستدعاء نموذج Node.js ويب API. يجب حماية واجهة برمجة تطبيقات الويب بواسطة Azure AD B2C نفسه. في هذا الإعداد، يقوم تطبيق ويب، مثل App ID: 1 باستدعاء واجهة برمجة تطبيقات ويب، مثل App ID: 2. يقوم المستخدمون بالمصادقة في تطبيق الويب للحصول على رمز مميز للوصول، والذي يستخدمونه لاستدعاء واجهة برمجة تطبيقات ويب محمية.

نظرة عامة

تضمن المصادقة القائمة على الرمز المميز أن الطلبات إلى واجهة برمجة تطبيقات الويب مصحوبة برمز وصول صالح.

يكمل تطبيق الويب الأحداث التالية:

يصادق المستخدمين باستخدام Microsoft Azure Active Directory B2C.
يكتسب رمز وصول مع الأذونات (النطاقات) المطلوبة لنقطة نهاية واجهة برمجة تطبيقات الويب.
يقوم بتمرير رمز الوصول كرمز مميز للحامل في رأس المصادقة لطلب HTTP. ويستخدم التنسيق التالي:

Authorization: Bearer <token>

تكمل واجهة برمجة تطبيقات الويب الأحداث التالية:

يقرأ رمز الحامل من رأس التفويض في طلب HTTP.
يتحقق من صحة الرمز المميز.
يتحقق من صحة الأذونات (النطاقات) في الرمز المميز.
يستجيب لطلب HTTP. إذا كان الرمز المميز غير صالح، تستجيب نقطة نهاية واجهة برمجة تطبيقات الويب بخطأ HTTP 401 Unauthorized.

تسجيل ملكية التطبيق

لتمكين التطبيق الخاص بك لتسجيل الدخول باستخدام Microsoft Azure AD B2C واستدعاء API ويب، فيجب عليك تسجيل تطبيقين في دليل Microsoft Azure AD B2C.

يمكن تسجيل تطبيق الويب تطبيقك من تسجيل الدخول باستخدام Azure AD B2C. أثناء تسجيل التطبيق، حدد إعادة توجيه URI. إعادة توجيه URI هي نقطة النهاية التي تُعيد توجيه المستخدمين من خلال Microsoft Azure AD B2C بعد تمام المصادقة. تنشئ عملية تسجيل التطبيق معرف تطبيق، يعرف أيضا باسم معرف العميل، والذي يحدد تطبيقك بشكل فريد. ستقوم أيضًا بإنشاء بيانات سرية لعميل لتطبيقك. يستخدم التطبيق الخاص بك البيانات السرية للعميل لتبادل رمز تخويل كرمز الوصول.
يمكّن تسجيل واجهة برمجة تطبيقات الويب تطبيقك من استدعاء واجهة برمجة تطبيقات ويب آمنة. يتضمن التسجيل نطاقات واجهة برمجة تطبيقات الويب. توفر النطاقات طريقة لإدارة أذونات الموارد المحمية، مثل واجهة برمجة تطبيقات الويب API. أنت تمنح أذونات تطبيق الويب لنطاقات واجهة برمجة تطبيقات الويب API. عند طلب رمز وصول، يحدد التطبيق الأذونات المطلوبة في معلمة النطاق الخاصة بالطلب.

يتم وصف تسجيلات التطبيق وبنية التطبيق في الرسم البياني التالي:

Diagram of the application registrations and the application architecture for an app with web A P I.

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

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

الخطوة 1: تكوين تدفق المستخدم الخاص بك

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

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

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

يسبق Microsoft Azure AD B2C B2C_1_اسم تدفق المستخدم. على سبيل المثال، يصبح susiB2C_1_susi.

الخطوة 2: تسجيل تطبيق الويب الخاص بك وواجهة برمجة التطبيقات

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

الخطوة 2.1: قم بتسجيل تطبيق Web API

لإنشاء تسجيل تطبيق واجهة برمجة تطبيقات الويب (App ID: 2)، اتبع الخطوات التالية:

سجل الدخول إلى مدخل Azure.
تأكد من استخدام الدليل الذي يحتوي على مستأجر Azure AD B2C. حدّد أيقونة الدلائل + الاشتراكات في شريط أدوات المدخل.
في صفحة Portal settings | Directories + subscriptions ابحث عن دليل Azure AD B2C في قائمة Directory name ثم حدّد Switch.
في مدخل Microsoft Azure، ابحث عن Azure AD B2C وحددها.
حدد App registrations، ثم حدد New registration.
تحت Name، أدخل اسمًا للتطبيق (على سبيل المثال، my-api1). اترك القيم الافتراضية لـ Redirect URIوأنواع الحسابات المدعومة.
حدد تسجيل.
بعد اكتمال عملية تسجيل التطبيق، حدد "Overview".
سجل قيمة Application (client) ID لاستخدامه لاحقًا عند تكوين تطبيق الويب.

الخطوة 2.2: تكوين النطاقات

حدد التطبيق my-api1 الذي أنشأته (App ID: 2) لفتح صفحة Overview الخاصة به.
ضمن إدارة، حدد كشف واجهة برمجة تطبيقات.
بجوار معرف التطبيق URI، حدد رابط تعيين. استبدل القيمة الافتراضية (GUID) باسم فريد (على سبيل المثال، tasks-api) ثم حدد Save.

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

الخطوة 2.3: تسجيل تطبيق الويب

لإنشاء تسجيل SPA، قم بما يلي:

سجل الدخول إلى مدخل Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد رمز الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة Directories + subscriptions.
ابحث عن Azure AD B2C وحدده.
حدد App registrations، ثم حدد New registration.
تحت Name، أدخل اسمًا للتطبيق (على سبيل المثال، my-api1).
ضمن أنواع الحسابات المدعومة، حدد الحسابات في أي موفر هوية أو دليل تنظيمي (لمصادقة المستخدمين بعمليات سير عمل المستخدمين).
من عنوان URI لإعادة التوجيه، حدد الويب، ثم أدخل http://localhost:3000/redirect في المربع النصي لعنوان URL.
ضمنأذونات الوصول، حدد مربع الاختيارلمنح موافقة المسؤول لفتح أذونات دخول والوصول عند عدم الاتصال بالإنترنت.
حدد تسجيل.

الخطوة 2.4: أنشئ بيانات سرية للعميل

في صفحة Azure Active Directory B2C - App registrations ، حدد التطبيق الذي أنشأته، ليكن على سبيل المثال webapp1 .
من القائمة اليسرى، ضمن Manage ، حدد Certificates & secrets.
حدد سر عميل جديد.
أدخل وصفاً لسر العميل في خانة Description . ليكن clientsecret1 على سبيل المثال.
من Expires ، حدد مدة صلاحية السر، ثم حدد Add .
سجّل القيمة المستخدمة للسر في التعليمة البرمجية لتطبيق عميلك. لا تُعرض هذه القيمة السرية مجدداًبعد مغادرة هذه الصفحة مطلقاً. يمكنك استخدام هذه القيمة كسر للتطبيق في التعليمة البرمجية لتطبيقك.

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

لمنح تطبيقك (App ID: 1) أذونات، اتبع الخطوات التالية:

حدد App registrations، ثم حدد التطبيق الذي قمت بإنشائه (معرف التطبيق: 1).
ضمن خانة الإدارة، اختر الأذونات الخاصة بواجهة برمجة التطبيقات.
ضمن أذونات مكونة، حدد إضافة إذن.
حدد علامة التبويب واجهات برمجة التطبيقات الخاصة بي.
حدد واجهة برمجة التطبيقات (App ID: 2) التي يجب منح تطبيق الويب حق الوصول إليها. على سبيل المثال، أدخل my-api1.
ضمن Permission، وسّع المهام، ثم حدد النطاقات التي حددتها سابقًا (على سبيل المثال، tasks.read وtasks.write).
حدد إضافة أذونات.
حدد «منح موافقة المسؤول لـ» <اسم المستأجر الخاص بك>.
حدد نعم.
حدد Refresh، ثم تحقق من ظهور منح لـ ... ضمن Status لكلا النطاقين.
من قائمة Configured permissions، حدد النطاق الخاص بك، ثم انسخ الاسم الكامل للنطاق.

الخطوة 3: احصل على التعليمة البرمجية للتطبيق العينة

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

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

قم بتنزيل ملف مضغوط. ستستخرج ملفًا مضغوطًا للحصول على تطبيق الويب العينة.

استنساخ العينة من GitHub عن طريق تشغيل الأمر التالي:

git clone https://github.com/Azure-Samples/active-directory-b2c-msal-node-sign-in-sign-out-webapp.git

الخطوة 3.1: تثبيت تبعيات التطبيق

افتح نافذة وحدة التحكم، وقم بالتغيير إلى الدليل الذي يحتوي على نموذج التطبيق Node.js. على سبيل المثال:
```
    cd active-directory-b2c-msal-node-sign-in-sign-out-webapp/call-protected-api
```
قم بتشغيل الأوامر التالية لتثبيت تبعيات التطبيق:
```
    npm install && npm update
```

الخطوة 3.2: تكوين تطبيق الويب العينة

افتح تطبيق الويب في محرر تعليمات برمجية مثل Visual Studio Code. تحت المجلد call-protected-api افتح الملف .env. يحتوي هذا الملف على معلومات حول موفر الهوية Microsoft Azure AD B2C. تحديث خواص إعدادات التطبيق التالية:

مفتاح	القيمة‬
`APP_CLIENT_ID`	معرف التطبيق (العميل) لتطبيق الويب الذي سجلته في الخطوة 2.3.
`APP_CLIENT_SECRET`	القيمة السرية للعميل لتطبيق الويب الذي أنشأته في الخطوة 2.4
`SIGN_UP_SIGN_IN_POLICY_AUTHORITY`	صلاحية تدفق المستخدم في تسجيل الدخول والاشتراك لتدفق المستخدم الذي قمت بإنشائه في الخطوة 1 مثل `https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<sign-in-sign-up-user-flow-name>`. استبدل `<your-tenant-name>` باسم المستأجر الخاص بك و`<sign-in-sign-up-user-flow-name>` باسم تدفق مستخدم تسجيل الدخول والتسجيل مثل `B2C_1_susi`. تعرف على كيفية الحصول على اسم المستأجر لديك.
`AUTHORITY_DOMAIN`	مجال جهة Azure AD B2C مثل `https://<your-tenant-name>.b2clogin.com`. استبدال `<your-tenant-name>` باسم مستأجرك.
`APP_REDIRECT_URI`	يعمل التطبيق على إعادة توجيه URI حيث يقوم Azure AD B2C بإرجاع استجابات المصادقة (الرموز المميزة). وهو يطابق إعادة توجيه URI الذي قمت بتعيينه أثناء تسجيل التطبيق الخاص بك في مدخل Azure. يجب أن يكون عنوان URL هذا متاحًا للجمهور. اترك القيمة كما هي.
`LOGOUT_ENDPOINT`	نقطة نهاية تسجيل خروج Azure AD B2C مثل `https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<sign-in-sign-up-user-flow-name>/oauth2/v2.0/logout?post_logout_redirect_uri=http://localhost:3000`. استبدل `<your-tenant-name>` باسم المستأجر الخاص بك و`<sign-in-sign-up-user-flow-name>` باسم تدفق مستخدم تسجيل الدخول والتسجيل مثل `B2C_1_susi`.

بعد التحديث، يجب أن يبدو ملف التكوين النهائي مشابهًا للعينة التالية:

SERVER_PORT=3000
#web apps client ID
APP_CLIENT_ID=<You app client ID here>
#session secret
SESSION_SECRET=sessionSecretHere
#web app client secret
APP_CLIENT_SECRET=<Your app client secret here>
#tenant name
TENANT_NAME=<your-tenant-name>
#B2C sign up and sign in user flow/policy name and authority
SIGN_UP_SIGN_IN_POLICY_AUTHORITY=https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<sign-in-sign-up-user-flow-name>
AUTHORITY_DOMAIN=https://<your-tenant-name>.b2clogin.com
#client redorect url
APP_REDIRECT_URI=http://localhost:3000/redirect
LOGOUT_ENDPOINT=https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<sign-in-sign-up-user-flow-name>/oauth2/v2.0/logout?post_logout_redirect_uri=http://localhost:3000

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

الآن بعد أن تم تسجيل واجهة برمجة تطبيقات الويب وحددت نطاقاتها، قم بتكوين رمز واجهة برمجة تطبيقات الويب للعمل مع مستأجر Azure AD B2C.

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

تنزيل أرشيف بتنسيق .zip*.
استنساخ نموذج مشروع واجهة برمجة تطبيقات الويب من GitHub عن طريق تشغيل الأمر التالي:
```
git clone https://github.com/Azure-Samples/active-directory-b2c-javascript-nodejs-webapi.git
```
يمكنك أيضا الانتقال مباشرة إلى مشروع Azure-Samples/active-directory-b2c-javascript-nodejs-webapi على GitHub.

الخطوة 4.1: تحديث واجهة برمجة تطبيقات الويب

في محرر التعليمات البرمجية، افتح الملف config.json.
قم بتعديل قيم المتغيرات باستخدام تسجيل التطبيق الذي قمت بإنشائه مسبقًا:
- بالنسبة tenantName، استخدم اسم المستأجر الخاص بك مثلfabrikamb2c.
- بالنسبة إلى clientID، استخدم معرف التطبيق (العميل) لواجهة برمجة تطبيق الويب الذي أنشأته في الخطوة 2.1.
- بالنسبة لـpolicyName، استخدم اسم تدفق المستخدم لتسجيل الدخول والتسجيل الذي أنشأته في الخطوة 1 مثلB2C_1_susi.
بعد التحديث، يجب أن تبدو التعليمات البرمجية مشابهة للعينة التالية:

config.json:
```
{
    "credentials": {
        "tenantName": "fabrikamb2c",
        "clientID": "93733604-cc77-4a3c-a604-87084dd55348"
    },
    "policies": {
        "policyName": "B2C_1_susi"
    },
    "resource": {
        "scope": ["tasks.read"]
    },
    "metadata": {
        "authority": "login.microsoftonline.com",
        "discovery": ".well-known/openid-configuration",
        "version": "v2.0"
    },
    "settings": {
        "isB2C": true,
        "validateIssuer": true,
        "passReqToCallback": false,
        "loggingLevel": "info"
    }
}
```

الخطوة 4.2: تثبيت تبعيات التطبيق

افتح نافذة وحدة التحكم، وقم بالتغيير إلى الدليل الذي يحتوي على نموذج واجهة برمجة تطبيقات الويب Node.js. على سبيل المثال:
```
cd active-directory-b2c-javascript-nodejs-webapi
```
شغّل الأوامر التالية:
```
npm install && npm update
```

الخطوة 5: تشغيل تطبيق الويب و API

أنت الآن جاهز لاختبار الوصول المحدد لتطبيق الويب إلى واجهة برمجة التطبيقات. قم بتشغيل كل من واجهة برمجة تطبيقات الويب Node.js، والتطبيق العينة JavaScript عى جهازك المحلي.

في المحطة الطرفية، انتقل إلى واجهة برمجة التطبيق العينة وشغل بدء تشغيل خادم API Node.js ويب. على سبيل المثال
```
cd active-directory-b2c-javascript-nodejs-webapi
node index.js
```
تعرض نافذة وحدة التحكم رقم المنفذ الخاص بالمكان الذي يستضيف فيه التطبيق.
```
Listening on port 5000...
```
في مثيل محطة طرفية آخر، انتقل إلى التطبيق العينة ثم قم بتشغيل تشغيل خادم تطبيق الويب Node.js. على سبيل المثال:
```
    cd active-directory-b2c-msal-node-sign-in-sign-out-webapp/call-protected-api
    node index.js
```
تعرض نافذة وحدة التحكم رقم المنفذ الخاص بالمكان الذي يستضيف فيه التطبيق.
```
Msal Node Auth Code Sample app listening on port !3000
```
في المتصفح الخاص بك، انتقل إلى http://localhost:3000. ينبغي أن تظهر لك صفحة بزرين Sign in to call PROTECTED APIو Or call the ANONYMOUS API.
لاستدعاء واجهة برمجة تطبيقات مجهولة، حدد Or call the ANONYMOUS API. تستجيب API مع كائن JSON بمفتاح date مثل:
```
    {"date":"2022-01-27T14:21:22.681Z"}
```
واجهة برمجة التطبيقات المجهولة هي نقطة نهاية غير محمية في واجهة برمجة تطبيقات الويب. لا تحتاج إلى رمز وصول للوصول إليها.
لاستدعاء نقطة نهاية API المحمية، حدد الزر Sign in to call PROTECTED API. تتم مطالبتك بتسجيل الدخول.
أدخل بيانات اعتماد تسجيل الدخول مثل عنوان البريد الإلكتروني وكلمة المرور. إذا لم يكن لديك حساب، فحدد التسجيل الآن لإنشاء حساب. بعد تسجيل الدخول أو التسجيل بنجاح، يجب أن تشاهد الصفحة التالية مع زر استدعاء واجهة برمجة تطبيقات محمية.
لاستدعاء API المحمية، حدد الزر Call the PROTECTED API. تستجيب API مع كائن JSON بمفتاح name قيمته هي اسم العائلة في حسابك مثل:
```
    {"name": "User 1"} 
```

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

تعرف على تمكين المصادقة في واجهة برمجة تطبيق الويب الخاص بك باستخدام ِAzure AD B2C