قم بتكوين المصادقة في نموذج تطبيق أحادي الصفحة باستخدامAzure AD B2C

مقالة
01/11/2024

تستخدم هذه المقالة نموذجًا لتطبيق JavaScript أحادي الصفحة (SPA)؛ لتوضيح كيفية إضافة مصادقةAzure Active Directory B2C (Azure AD B2C) إلى SPA الخاصة بك.

نظرة عامة

OID الاتصال (OIDC) هو بروتوكول مصادقة مبني على OAuth 2.0. يمكنك استخدامه لتسجيل دخول المستخدم بأمان إلى أحد التطبيقات. تستخدم عينة SPA هذا MSAL.js والتدفق OIDC PKCE. MSAL.js هي مكتبة توفرها Microsoft تعمل على تبسيط إضافة دعم المصادقة والتفويض إلى SPAs.

يتضمن تدفق تسجيل الدخول الخطوات التالية:

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

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

لتمكين تطبيقك من تسجيل الدخول باستخدام Azure AD B2C واستدعاء واجهة برمجة تطبيقات الويب، يمكنك تسجيل تطبيقين في دليل Azure AD B2C.

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

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

Diagram of a web app with web API call registrations and tokens.

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

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

Authorization: Bearer <access token>

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

تدفق تسجيل الخروج

يتضمن تدفق تسجيل الخروج الخطوات التالية:

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

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

جهاز الكمبيوتر قيد التشغيل:

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

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

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

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

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

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

الخطوة 2: تسجيل SPA و API

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

الخطوة 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

لإنشاء تسجيل SPA، استخدم الخطوات التالية:

سجل الدخول إلى مدخل Azure.
إذا كان لديك حق الوصول إلى عدة مستأجرين، فحدد رمز الإعدادات في القائمة العلوية للتبديل إلى مستأجر Azure AD B2C من قائمة Directories + subscriptions.
ابحث عن Azure AD B2C وحدده.
حدد App registrations، ثم حدد New registration.
أدخل اسما للتطبيق (على سبيل المثال، MyApp).
ضمن أنواع الحسابات المدعومة، حدد الحسابات في أي موفر هوية أو دليل تنظيمي (لمصادقة المستخدمين بعمليات سير عمل المستخدمين).
ضمن Redirect URI، حدد Single-page application (SPA)، وأدخِل http://localhost:6420 في المربع النصي لعنوان URL.
ضمنأذونات الوصول، حدد مربع الاختيارلمنح موافقة المسؤول لفتح أذونات دخول والوصول عند عدم الاتصال بالإنترنت.
حدد تسجيل.

سجل معرف التطبيق (العميل) لاستخدامه لاحقا، عند تكوين تطبيق الويب.

Screenshot of the web app Overview page for recording your web application ID.

الخطوة 2.4: تمكين تدفق المنح الضمني

في بيئتك الخاصة، إذا كان تطبيق SPA الخاص بك يستخدم MSAL.js 1.3 أو إصدار أقدم وتدفق المنحة الضمني أو قمت بتكوين التطبيق https://jwt.ms/ لاختبار تدفق مستخدم أو نهج مخصص، فأنت بحاجة إلى تمكين تدفق المنحة الضمني في تسجيل التطبيق:

من القائمة اليسرى، تحت خانة "Manage"، حدد "Authentication".
ضمن المنحة الضمنية والتدفقات المختلطة، حدد خانتي الاختيار الرموز المميزة للوصول (المستخدمة للتدفقات الضمنية) والرموز المميزة للمعرف (المستخدمة للتدفقات الضمنية والمختلطة).
حدد حفظ.

إذا كان تطبيقك يستخدم MSAL.js 2.0 أو أحدث، فلا تقم بتمكين منحة التدفق الضمنية لأن MSAL.js 2.0+ يدعم تدفق التعليمات البرمجية للتخويل باستخدام PKCE. يستخدم تطبيق SPA في هذه المقالة تدفق PKCE، وبالتالي لا تحتاج إلى تمكين تدفق المنح الضمني.

الخطوة 2.5: منح الأذونات

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

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

الخطوة 3: احصل على نموذج رمز SPA

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

للحصول على نموذج كود SPA، يمكنك القيام بأي مما يلي:

قم بتنزيل ملف مضغوط.
استنساخ العينة من GitHub عن طريق تشغيل الأمر التالي:
```
git clone https://github.com/Azure-Samples/ms-identity-b2c-javascript-spa.git
```

الخطوة 3.1: تحديث نموذج SPA

الآن بعد أن حصلت على عينة SPA، حدّث التعليمات البرمجية بقيم متاجرة عمل-مستهلك في Azure Active Directory وواجهة برمجة تطبيقات الويب. في المجلد النموذجي، ضمن App المجلد، افتح ملفات JavaScript المدرجة في الجدول التالي، ثم قم بتحديثها بالقيم المقابلة لها.

ملف	مفتاح	القيمة‬
authConfig.js	clientId	معرف SPA من الخطوة 2.3.
السياسات. Js	names	يتدفق المستخدم أو النهج المخصص الذي أنشأته في الخطوة 1.
السياسات. Js	authorities	تدفقات مستخدم Azure AD B2C أو سلطات النهج المخصصة مثل `https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<your-sign-in-sign-up-policy>`. استبدال `your-sign-in-sign-up-policy` بتدفق مستخدم أو النهج المخصص التي أنشأتها في الخطوة 1
السياسات. Js	authorityDomain	مجال السلطة Azure AD B2C مثل `<your-tenant-name>.b2clogin.com`.
apiConfig.js	b2cسكوبات	نطاقات واجهة برمجة تطبيقات الويب التي قمت بإنشائها في الخطوة 2.2 (على سبيل المثال، `b2cScopes: ["https://<your-tenant-name>.onmicrosoft.com/tasks-api/tasks.read"]` ).
apiConfig.js	webApi	عنوان URL لواجهة برمجة تطبيقات الويب، `http://localhost:5000/hello`.

يجب أن تبدو التعليمات البرمجية الناتجة مشابهة للعينة التالية:

authConfig.js:

const msalConfig = {
    auth: {
      clientId: "<your-MyApp-application-ID>", // This is the ONLY mandatory field; everything else is optional.
      authority: b2cPolicies.authorities.signUpSignIn.authority, // Choose sign-up/sign-in user-flow as your default.
      knownAuthorities: [b2cPolicies.authorityDomain], // You must identify your tenant's domain as a known authority.
      redirectUri: "http://localhost:6420", // You must register this URI on Azure Portal/App Registration. Defaults to "window.location.href".
    },
    cache: {
      cacheLocation: "sessionStorage",  
      storeAuthStateInCookie: false, 
    },
    system: {
      loggerOptions: {
        loggerCallback: (level, message, containsPii) => {
          if (containsPii) {
            return;
          }
          switch (level) {
            case msal.LogLevel.Error:
              console.error(message);
              return;
            case msal.LogLevel.Info:
              console.info(message);
              return;
            case msal.LogLevel.Verbose:
              console.debug(message);
              return;
            case msal.LogLevel.Warning:
              console.warn(message);
              return;
          }
        }
      }
    }
  };
};

const loginRequest = {
  scopes: ["openid", ...apiConfig.b2cScopes],
};

const tokenRequest = {
  scopes: [...apiConfig.b2cScopes],  // e.g. ["https://fabrikamb2c.onmicrosoft.com/helloapi/demo.read"]
  forceRefresh: false // Set this to "true" to skip a cached token and go to the server to get a new token
};

policies.js:

const b2cPolicies = {
    names: {
        signUpSignIn: "b2c_1_susi",
        forgotPassword: "b2c_1_reset",
        editProfile: "b2c_1_edit_profile"
    },
    authorities: {
        signUpSignIn: {
            authority: "https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com/b2c_1_susi",
        },
        forgotPassword: {
            authority: "https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com/b2c_1_reset",
        },
        editProfile: {
            authority: "https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com/b2c_1_edit_profile"
        }
    },
    authorityDomain: "your-tenant-name.b2clogin.com"
}

apiConfig.js:

const apiConfig = {
  b2cScopes: ["https://your-tenant-name.onmicrosoft.com/tasks-api/tasks.read"],
  webApi: "http://localhost:5000/hello"
};

الخطوة 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 في محرر التعليمات البرمجية.
قم بتعديل قيم المتغيرات باستخدام تسجيل التطبيق الذي قمت بإنشائه مسبقًا. وحدث policyName مع تدفق المستخدم الذي قمت بإنشائه كجزء من المتطلبات الأساسية (على سبيل المثال، b2c_1_susi).
```
"credentials": {
    "tenantName": "<your-tenant-name>",
    "clientID": "<your-webapi-application-ID>"
},
"policies": {
    "policyName": "b2c_1_susi"
},
"resource": {
    "scope": ["tasks.read"] 
},
```

الخطوة 4.2: تمكين CORS

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

لتمكين CORS، استخدم البرامج الوسيطة التالية. في نموذج التعليمات البرمجية لواجهة برمجة تطبيقات الويب Node.js الذي قمت بتنزيله، تمت إضافته بالفعل إلى ملف index.js .

app.use((req, res, next) => {
    res.header("Access-Control-Allow-Origin", "*");
    res.header("Access-Control-Allow-Headers", "Authorization, Origin, X-Requested-With, Content-Type, Accept");
    next();
});

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

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

قم بتشغيل واجهة برمجة تطبيقات الويب Node.js

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

قم بتشغيل التطبيق أحادي الصفحة

افتح نافذة وحدة تحكم أخرى، وقم بالتغيير إلى الدليل الذي يحتوي على نموذج JavaScript SPA. على سبيل المثال:
```
cd ms-identity-b2c-javascript-spa
```
شغّل الأوامر التالية:
```
npm install && npm update
npm start
```
تعرض نافذة وحدة التحكم رقم المنفذ الخاص بالمكان الذي يستضيف فيه التطبيق.
```
Listening on port 6420...
```
لعرض التطبيق، انتقل إلى http://localhost:6420 في المستعرض.
أكمل عملية التسجيل أو تسجيل الدخول. بعد تسجيل الدخول بنجاح، يجب أن ترى رسالة "المستخدم <اسم المستخدم خاصتك> الذي سجل الدخول.
حدد الزر Call API. يرسل SPA رمز الوصول في طلب إلى واجهة برمجة تطبيقات الويب API المحمية، والتي تُرجع اسم العرض للمستخدم الذي قام بتسجيل الدخول:

نشر تطبيقك

في التطبيق المنتج، يكون عنوان URI لإعادة توجيه تسجيل التطبيق عادةً نقطة نهاية يمكن الوصول إليها بشكل عام حيث يتم تشغيل التطبيق، مثلhttps://contoso.com/signin-oidc.

يمكنك إضافة وتعديل عناوين "URI" لإعادة التوجيه في تطبيقاتك المسجلة في أي وقت. تنطبق القيود التالية على إعادة توجيه عناوين "URI":

يجب أن يبدأ عنوان URL للرد بنظام https.
يكون عنوان "URL" للرد حساسًا لحالة الأحرف. يجب أن تتطابق حالته مع حالة مسار عنوان "URL" للتطبيق قيد التشغيل.

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

لمزيد من المعلومات حول المفاهيم التي تمت مناقشتها في هذه المقالة: