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

  • مقالة

توضح هذه المقالة كيفية تمكين تجربة مصادقة Azure Active Directory B2C (Azure AD B2C) وتخصيصها وتحسينها لتطبيق الويب Node.js لديك.

قبل البدء، من المهم التعرف على المقالات التالية:

استخدام مجال مخصص

باستخدام custom domain، يمكنك وضع علامة تجارية كاملة على عنوان URL للمصادقة. من منظور المستخدم، يظل المستخدمون في المجال الخاص بك أثناء عملية المصادقة، بدلاً من إعادة توجيههم إلى اسم مجال Microsoft Azure Active Directory B2C b2clogin.com.

لإزالة كافة الإشارات إلى "b2c" في عنوان URL، يمكنك أيضاً استبدال اسم مستأجر B2C الخاص بك، contoso.onmicrosoft.com، في عنوان URL لطلب المصادقة مع معرف المستأجر GUID. على سبيل المثال، يمكنك تغيير https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ إلى https://account.contosobank.co.uk/<tenant ID GUID>/.

لاستخدام مجال مخصص ومعرف المستأجر الخاص بك في عنوان URL للمصادقة، اتبع الإرشادات الموجودة في تمكين المجالات المخصصة. ضمن المجلد الجذر للمشروع، افتح ملف المجلد الجذر ‎.env. يحتوي هذا الملف على معلومات حول موفر الهوية Microsoft Azure AD B2C.

في ملف ‎.env، قم بما يلي:

  • استبدل كافة مثيلات tenant-name.b2clogin.com بالمجال المخصص. على سبيل المثال، استبدل tenant-name.b2clogin.com، إلى login.contoso.com.
  • استبدل كافة مثيلات tenant-name.onmicrosoft.com بـ معرف المستأجر. لمزيد من المعلومات، راجع استخدام معرف المستأجر.

يعرض التكوين التالي إعدادات التطبيق قبل التغيير:

#B2C sign up and sign in user flow/policy authority
SIGN_UP_SIGN_IN_POLICY_AUTHORITY=https://contoso.b2clogin.com/contoso.onmicrosoft.com/B2C_1_susi
#B2C password reset user flow/policy authority
RESET_PASSWORD_POLICY_AUTHORITY=https://contoso.b2clogin.com/contoso.onmicrosoft.com/B2C_1_passwordreset
#B2C edit profile user flow/policy authority
EDIT_PROFILE_POLICY_AUTHORITY=https://contoso.b2clogin.com/contoso.onmicrosoft.com/B2C_1_edit
#B2C authority domain
AUTHORITY_DOMAIN=https://contoso.b2clogin.com
#client redirect url
APP_REDIRECT_URI=http://localhost:3000/redirect
#Logout endpoint 
LOGOUT_ENDPOINT=https://contoso.b2clogin.com/contoso.onmicrosoft.com/B2C_1_susi/oauth2/v2.0/logout?post_logout_redirect_uri=http://localhost:3000

يعرض التكوين التالي إعدادات التطبيق بعد التغيير:

#B2C sign up and sign in user flow/policy authority
SIGN_UP_SIGN_IN_POLICY_AUTHORITY=https://login.contoso.com/12345678-0000-0000-0000-000000000000/B2C_1_susi
#B2C password reset user flow/policy authority
RESET_PASSWORD_POLICY_AUTHORITY=https://login.contoso.com/12345678-0000-0000-0000-000000000000/B2C_1_passwordreset
#B2C edit profile user flow/policy authority
EDIT_PROFILE_POLICY_AUTHORITY=https://login.contoso.com/12345678-0000-0000-0000-000000000000/B2C_1_edit
#B2C authority domain
AUTHORITY_DOMAIN=https://login.contoso.com
#client redirect url
APP_REDIRECT_URI=http://localhost:3000/redirect
#Logout endpoint 
LOGOUT_ENDPOINT=https://login.contoso.com/12345678-0000-0000-0000-000000000000/B2C_1_susi/oauth2/v2.0/logout?post_logout_redirect_uri=http://localhost:3000

ملء اسم تسجيل الدخول مسبقًا

أثناء قيام المستخدم بتسجيل الدخول، قد يستهدف تطبيقك مستخدماً معيناً. عندما يستهدف أحد التطبيقات مستخدماً، يمكنه تحديد معلمة طلب البحث login_hint في طلب التفويض باسم تسجيل دخول المستخدم. يملأ Microsoft Azure Active Directory B2C اسم تسجيل الدخول تلقائياً، ويحتاج المستخدم إلى توفير كلمة المرور فقط.

لملء اسم تسجيل الدخول مسبقاً، قم بما يلي:

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

توضح مقتطفات التعليمات البرمجية التالية كيفية تمرير معلمة تلميح تسجيل الدخول. وتستخدم bob@contoso.com كقيمة السمة.

authCodeRequest.loginHint = "bob@contoso.com"

return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)
        .then((response) => {

حدد موفر الهوية مسبقاً

إذا قمت بتكوين رحلة «sign-in» لتطبيقك من أجل تضمين الحسابات الاجتماعية، مثل Facebook أو LinkedIn أو Google، يمكنك تحديد المعلمة domain_hint. توفر معلمة الاستعلام تلميح إلى Azure AD B2C حول موفر الهوية الاجتماعية التي يجب استخدامها لـ «sign-in». على سبيل المثال، إذا حدد التطبيق domain_hint=facebook.com، ينتقل تدفق تسجيل الدخول مباشرة إلى صفحة تسجيل الدخول إلى Facebook.

لإعادة توجيه المستخدمين إلى موفر هوية خارجي، قم بما يلي:

  1. تحقق من اسم المجال لموفر الهوية الخارجي الخاص بك. لمزيد من المعلومات، راجع إعادة توجيه تسجيل الدخول إلى موفر الخدمة الاجتماعي.
  2. ابحث عن عنصر authCodeRequest، وقم بتعيين السمة domainHint مع تلميح المجال المطابق.

توضح مقتطفات التعليمات البرمجية التالية كيفية تمرير معلمة تلميح المجال. ويستخدم facebook.com كقيمة السمة.

authCodeRequest.domainHint = "facebook.com"

return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)
        .then((response) => {

حدد لغة واجهة المستخدم

يتيح تخصيص اللغة في Microsoft Azure Active Directory B2C تدفق المستخدم لاستيعاب مجموعة متنوعة من اللغات لتناسب احتياجات عملائك. لمزيد من المعلومات، راجع تخصيص اللغة.

لتعيين اللغة المفضلة، قم بما يلي:

  1. تكوين تخصيص اللغة.
  2. ابحث عن عنصر authCodeRequest، وقم بتعيين السمة extraQueryParameters بالمعلمة الإضافية المطابقة ui_locales.

توضح قصاصات التعليمات البرمجية التالية كيفية تمرير معلمة ui_locales. وتستخدم es-es كقيمة السمة.

authCodeRequest.extraQueryParameters = {"ui_locales" : "es-es"}

return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)
        .then((response) => {

قم بتمرير معلمة سلسلة طلب بحث مخصصة

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

لتمرير معلمة سلسلة طلب بحث مخصصة، قم بما يلي:

  1. تكوينعنصر ContentDefinitionParameters.
  2. ابحث عن عنصر authCodeRequest، وقم بتعيين السمة extraQueryParameters بالمعلمة الإضافية المطابقة.

توضح قصاصات التعليمات البرمجية التالية كيفية تمرير معلمة سلسلة الاستعلام المخصصة campaignId. وتستخدم germany-promotion كقيمة السمة.

authCodeRequest.extraQueryParameters = {"campaignId" : "germany-promotion"}

return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)
        .then((response) => {

تمرير تلميح رمز معرف

يمكن لتطبيق الطرف المعتمد إرسال رمز ويب JSON وارد (JWT) كجزء من طلب تفويض OAuth2. الرمز المميز الوارد هو تلميح حول المستخدم أو طلب التفويض. يتحقق Microsoft Azure Active Directory B2C من صحة الرمز المميز ثم يستخرج المطالبة.

لتضمين تلميح رمز مميز للمعرف في طلب المصادقة، قم بما يلي:

  1. في سياستك المخصصة، حدد ملف تعريف تقني تلميح رمز مميز للمعرف.
  2. ابحث عن عنصر authCodeRequest، وقم بتعيين السمة extraQueryParameters بالمعلمة الإضافية المطابقة id_token_hint.

توضح مقتطفات التعليمات البرمجية التالية كيفية تحديد تلميح رمز مميز للمعرف:

authCodeRequest.extraQueryParameters = {"id_token_hint": idToken}

return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)

تكوين التسجيل

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

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

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

بشكل افتراضي، لا يلتقط مسجل MSAL أي بيانات شخصية أو تنظيمية. تَمنحك المكتبة خيار تمكين تسجيل البيانات الشخصية والتنظيمية إذا قررت القيام بذلك.

لتكوين تسجيل الدخول، في index.js، قم بتكوين المفاتيح التالية:

  • logLevel يتيح لك تحديد مستوى التسجيل. القيم المحتملة:ErrorوWarningوInfoوVerbose.
  • piiLoggingEnabled تمكين إدخال البيانات الشخصية. القيم المحتملة: true أو false.

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

 const confidentialClientConfig = {
    ...
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: msal.LogLevel.Verbose,
        }
    }
};

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

قم بالتعرف على المزيد حول خيارات تكوين MSAL.js.