تمكين المصادقة في واجهة برمجة تطبيقات الويب الخاصة بك باستخدام Microsoft Azure Active Directory B2C

لتخويل الوصول إلى واجهة برمجة تطبيقات الويب، يمكنك تقديم الطلبات التي تتضمن رمز وصول صالحا لمشكلات متاجرة العمل-المستهلك في Azure Active Directory (Azure AD B2C). توضح لك هذه المقالة كيفية تمكين ترخيص Microsoft Azure Active Directory B2C لواجهة برمجة تطبيقات الويب الخاصة بك. بعد إكمال الخطوات الواردة في هذه المقالة، سيتم السماح للمستخدمين الذين يحصلون على رمز وصول صالح فقط بالاتصال بنقاط نهاية واجهة برمجة تطبيقات الويب الخاصة بك.

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

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

• تكوين المصادقة في نموذج تطبيق ASP.NET Core
• تكوين المصادقة في نموذج تطبيق أحادي الصفحة (SPA)

نظرة عامة

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

يكمل التطبيق الخطوات التالية:

1. يصادق المستخدمين باستخدام Microsoft Azure Active Directory B2C.

2. يكتسب رمز وصول مع الأذونات (النطاقات) المطلوبة لنقطة نهاية واجهة برمجة تطبيقات الويب.

3. يقوم بتمرير رمز الوصول كرمز حامل في رأس المصادقة لطلب HTTP باستخدام هذا التنسيق:

   Authorization: Bearer <access token>
   

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

1. يقرأ رمز الحامل من رأس التفويض في طلب HTTP.

2. يتحقق من صحة الرمز المميز.

3. يتحقق من صحة الأذونات (النطاقات) في الرمز المميز.

4. يقرأ المطالبات التي تم ترميزها في الرمز المميز (اختياري).

5. يستجيب لطلب HTTP.

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

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

• يمكّن تسجيل تطبيق الويب أو الهاتف المحمول أو SPA تطبيقك من تسجيل الدخول باستخدام Microsoft Azure Active Directory B2C. تنشئ عملية تسجيل التطبيق معرّف التطبيق، المعروف أيضًا باسم معرّف العميل، والذي يعرّف تطبيقك بشكل فريد (على سبيل المثال، معرّف التطبيق: 1).

• يتيح تسجيلAPI ويبلتطبيقك الاتصال API ويب المحمية. يعرض التسجيل أذونات الوصول واجهة برمجة تطبيقات الويب (النطاقات). تنشئ عملية تسجيل التطبيق معرّف التطبيق، الذي يعرّف بشكل فريد واجهة برمجة تطبيقات الويب (على سبيل المثال، معرّف التطبيق: 2). منح التطبيق (معرّف التطبيق: 1) أذونات لنطاقات واجهة برمجة تطبيقات الويب (معرّف التطبيق: 2).

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

جهز بيئة التطوير الخاصة بك

في الأقسام التالية، يمكنك إنشاء مشروع واجهة برمجة تطبيقات ويب جديد. حدد لغة البرمجة الخاصة بك، ASP.NET Core أو Node.js. تأكد من أن لديك جهاز كمبيوتر يعمل بأي من البرامج التالية:

ASP.NET Core

• Visual Studio Code
• C# for Visual Studio Code (أحدث إصدار)
• .NET 5.0 SDK

Node.js

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

الخطوة 1: إنشاء واجهة برمجة تطبيقات ويب محمية

إنشاء مشروع جديد لواجهة برمجة تطبيقات الويب. أولًا، حدد لغة البرمجة التي تريد استخدامها، ASP.NET CoreاوNode.js.

ASP.NET Core

استخدم الأمرdotnet new. يقوم dotnet newالأمر بإنشاء مجلد جديد يسمىTodoListمع أصول مشروع واجهة برمجة تطبيقات الويب. افتح الدليل، ثم افتحVisual Studio Code.

dotnet new webapi -o TodoList
cd TodoList
code . 

عندما يُطلب منك "إضافة الأصول المطلوبة إلى المشروع"، حدد"نعم".

Node.js

استخدم Express لـ Node.js لبناء واجهة برمجة تطبيقات الويب. لإنشاء واجهة برمجة تطبيقات ويب، قم بما يلي:

1. قم بإنشاء مجلد جديد باسم TodoList.
2. ضمن مجلد TodoList، أنشئ ملفًا باسم app.js.
3. في قذيفة الأوامر، قم بتشغيلnpm init -y. يقوم هذا الأمر بإنشاء package.js افتراضي على ملف لمشروع Node.js.
4. في الأمر shell، قم بتشغيل npm install express. يثبّت هذا الأمر إطار عمل Express.

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

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

ASP.NET Core

لإضافة مكتبة المصادقة، قم بتثبيت الحزمة عن طريق تشغيل الأمر التالي:

dotnet add package Microsoft.Identity.Web

Node.js

لإضافة مكتبة المصادقة، قم بتثبيت الحزم عن طريق تشغيل الأمر التالي:

npm install passport
npm install passport-azure-ad
npm install morgan

إن حزمة morgan هي برنامج وسيطة مُسجّل لطلبات HTTP لـ Node.js.

الخطوة 3: ابدأ مكتبة المصادقة

أضف الكود اللازم لبدء مكتبة المصادقة.

ASP.NET Core

افتح Startup.cs ثم أضف usingالإعلانات التالية في بداية الفصل الدراسي:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

ابحث عن الدالة ConfigureServices(IServiceCollection services) . بعد ذلك، services.AddControllers();قبل سطر التعليمات البرمجية، أضف مقتطف الشفرة التالي:

public void ConfigureServices(IServiceCollection services)
{
    // Adds Microsoft Identity platform (Azure AD B2C) support to protect this Api
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddMicrosoftIdentityWebApi(options =>
    {
        Configuration.Bind("AzureAdB2C", options);

        options.TokenValidationParameters.NameClaimType = "name";
    },
    options => { Configuration.Bind("AzureAdB2C", options); });
    // End of the Microsoft Identity platform block    

    services.AddControllers();
}

ابحث عن الدالة Configure . بعد ذلك، مباشرةً بعد سطرapp.UseRouting(); التعليمات البرمجية، أضف مقتطف الشفرة التالي:

app.UseAuthentication();

بعد التغيير، يجب أن تبدو شفرتك مثل المقتطف التالي:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    app.UseRouting();
    
    // Add the following line 
    app.UseAuthentication();
    // End of the block you add
    
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Node.js

أضف كود JavaScript التالي إلى ملف app.js الخاص بك.

// Import the required libraries
const express = require('express');
const morgan = require('morgan');
const passport = require('passport');
const config = require('./config.json');

// Import the passport Azure AD library
const BearerStrategy = require('passport-azure-ad').BearerStrategy;

// Set the Azure AD B2C options
const options = {
    identityMetadata: `https://${config.credentials.tenantName}.b2clogin.com/${config.credentials.tenantName}.onmicrosoft.com/${config.policies.policyName}/${config.metadata.version}/${config.metadata.discovery}`,
    clientID: config.credentials.clientID,
    audience: config.credentials.clientID,
    issuer: config.credentials.issuer,
    policyName: config.policies.policyName,
    isB2C: config.settings.isB2C,
    scope: config.resource.scope,
    validateIssuer: config.settings.validateIssuer,
    loggingLevel: config.settings.loggingLevel,
    passReqToCallback: config.settings.passReqToCallback
}

// Instantiate the passport Azure AD library with the Azure AD B2C options
const bearerStrategy = new BearerStrategy(options, (token, done) => {
        // Send user info using the second argument
        done(null, { }, token);
    }
);

// Use the required libraries
const app = express();

app.use(morgan('dev'));

app.use(passport.initialize());

passport.use(bearerStrategy);

//enable CORS (for testing only -remove in production/deployment)
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();
});

الخطوة 4: أضف نقاط النهاية

أضف نقطتي نهاية إلى واجهة برمجة تطبيقات الويب الخاصة بك:

• /publicنقطة نهاية مجهولة. ترجع نقطة النهاية هذه للتاريخ والوقت الحاليين. استخدمه لتصحيح أخطاء واجهة برمجة تطبيقات الويب الخاصة بك باستخدام مكالمات مجهولة.
• /helloنقطة نهاية محمية. تقوم نقطة النهاية هذه بإرجاع قيمة nameالمطالبة داخل رمز الوصول.

لإضافة نقطة نهاية مجهولة:

ASP.NET Core

ضمن المجلد /Controllers، أضف ملف PublicController.cs، ثم أضفه إلى القصاصة البرمجية التالية:

using System;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace TodoList.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class PublicController : ControllerBase
    {
        private readonly ILogger<PublicController> _logger;

        public PublicController(ILogger<PublicController> logger)
        {
            _logger = logger;
        }

        [HttpGet]
        public ActionResult Get()
        {
            return Ok( new {date = DateTime.UtcNow.ToString()});
        }
    }
}

Node.js

في ملف app.js، أضف كود JavaScript التالي:

// API anonymous endpoint
app.get('/public', (req, res) => res.send( {'date': new Date() } ));

لإضافة نقطة النهاية المحمية:

ASP.NET Core

ضمن المجلد /Controllers، أضف ملف HelloController.cs، ثم أضفه إلى التعليمات البرمجية التالية:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Microsoft.Identity.Web.Resource;

namespace TodoList.Controllers
{
    [Authorize]
    [RequiredScope("tasks.read")]
    [ApiController]
    [Route("[controller]")]
    public class HelloController : ControllerBase
    {

        private readonly ILogger<HelloController> _logger;
        private readonly IHttpContextAccessor _contextAccessor;

        public HelloController(ILogger<HelloController> logger, IHttpContextAccessor contextAccessor)
        {
            _logger = logger;
            _contextAccessor = contextAccessor;
        }

        [HttpGet]
        public ActionResult Get()
        {
            return Ok( new { name = User.Identity.Name});
        }
    }
}

HelloControllerتم تزيين وحدة التحكم بـ AuthorizeAttribute، والذي يحد من الوصول إلى المستخدمين المصادق عليهم فقط.

تم تزيين وحدة التحكم أيضًا بـ[RequiredScope("tasks.read")]. تتحقق سمة النطاق المطلوبة من استدعاء واجهة برمجة تطبيقات الويب بالنطاقات الصحيحةtasks.read.

Node.js

في ملف app.js، أضف كود JavaScript التالي:

// API protected endpoint
app.get('/hello',
    passport.authenticate('oauth-bearer', {session: false}),
    (req, res) => {
        console.log('Validated claims: ', req.authInfo);
        
        // Service relies on the name claim.  
        res.status(200).json({'name': req.authInfo['name']});
    }
);

/helloتستدعي نقطة النهاية الوظيفة passport.authenticate()أولاً. تقيد وظيفة المصادقة الوصول إلى المستخدمين المصدق عليهم فقط.

تتحقق وظيفة المصادقة أيضًا من استدعاء واجهة برمجة تطبيقات الويب بالنطاقات الصحيحة. النطاقات المسموح بها موجودة في ملف التكوين.

الخطوة 5: تكوين خادم الويب

في بيئة التطوير، قم بتعيين واجهة برمجة تطبيقات الويب للاستماع إلى رقم منفذ طلبات HTTP أو HTTPS. في هذا المثال، استخدم منفذ HTTP 6000 ومنفذ HTTPS 6001. سيكون عنوان URI الأساسي لواجهة برمجة تطبيقات الويب مخصصًا لـhttp://localhost:6000 HTTP وhttps://localhost:6001 HTTPS.

ASP.NET Core

أضف مقتطف JSON التالي إلى ملف appsettings.json.

"Kestrel": {
    "EndPoints": {
      "Http": {
        "Url": "http://localhost:6000"
      },
      "Https": {
         "Url": "https://localhost:6001"   
        }
    }
  }

Node.js

أضف كود JavaScript التالي إلى ملف app.js. من الممكن إعداد نقاط نهاية HTTP وHTTPS لتطبيق Node.

// Starts listening on port 6000
const port = process.env.PORT || 6000;

app.listen(port, () => {
    console.log('Listening on port ' + port);
});

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

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

ASP.NET Core

ضمن المجلد الجذر للمشروع، افتح ملف appsettings.json، ثم أضف الإعدادات التالية:

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-api-app-application-id>",
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  // More settings here
}

في ملف appsettings.json، قم بتحديث الخصائص التالية:

المقطع	مفتاح	القيمة
AzureAdB2C	‏‏مثيل	الجزء الأول من اسم مستأجر Microsoft Azure Active Directory B2C (على سبيل المثال، https://contoso.b2clogin.com).
AzureAdB2C	النطاق	مستأجر خدمات مجال Microsoft Azure Active Directory B2C اسم المستأجر بالكامل (على سبيل المثال، contoso.onmicrosoft.com).
AzureAdB2C	ClientId	معرف تطبيق الويب API. في الرسم البياني السابق، إنه التطبيق مع معرف التطبيق: 2. لمعرفة كيفية الحصول على معرف تسجيل تطبيق الويب API، راجع المتطلبات الأساسية.
AzureAdB2C	SignUpSignInPolicyId	تدفقات المستخدم، أو السياسة المخصصة. لمعرفة كيفية الحصول على تدفق المستخدم أو النهج، راجع المتطلبات الأساسية.

Node.js

ضمن المجلد الجذر للمشروع، أنشئ ملف config.json ، ثم أضفه إلى مقتطف JSON التالي:

{
    "credentials": {
        "tenantName": "<your-tenant-name>.onmicrosoft.com",
        "clientID": "<your-webapi-application-ID>",
        "issuer": "https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/"
    },
    "policies": {
        "policyName": "b2c_1_susi"
    },
    "resource": {
        "scope": ["tasks.read"]
    },
    "metadata": {
        "discovery": ".well-known/openid-configuration",
        "version": "v2.0"
    },
    "settings": {
        "isB2C": true,
        "validateIssuer": true,
        "passReqToCallback": false,
        "loggingLevel": "info"
    }
}

في ملف config.json، قم بتحديث الخصائص التالية:

المقطع	مفتاح	القيمة
بيانات الاعتماد	الاسم الخاص بالمستأجر	اسم/اسم مجال مستأجر Azure AD B2C (على سبيل المثال contoso.onmicrosoft.com).
بيانات الاعتماد	clientID	معرف تطبيق الويب API. في الرسم البياني السابق، إنه التطبيق مع معرف التطبيق: 2. لمعرفة كيفية الحصول على معرف تسجيل تطبيق الويب API، راجع المتطلبات الأساسية.
بيانات الاعتماد	المُصدر	قيمة مطالبة مُصدر الرمزiss المميز. بشكل افتراضي، يقوم Microsoft Azure Active Directory B2C بإرجاع الرمز المميز بالتنسيق التالي:https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. استبدل <your-tenant-name> بالجزء الأول من اسم مستأجر متاجرة عمل-مستهلك في Azure Active Directory. استبدل <your-tenant-ID> بـ معرّف مستأجر متاجرة عمل-مستهلك في Azure Active Directory.
النُهج	policyName	تدفقات المستخدم، أو السياسة المخصصة. لمعرفة كيفية الحصول على تدفق المستخدم أو النهج، راجع المتطلبات الأساسية.
resource	النطاق	نطاقات تسجيل تطبيق الويب API الخاص بك. لمعرفة كيفية الحصول على نطاق واجهة برمجة تطبيقات الويب، راجع المتطلبات الأساسية.

الخطوة 7: قم بتشغيل واختبار واجهة برمجة تطبيقات الويب

أخيرًا، قم بتشغيل واجهة برمجة تطبيقات الويب باستخدام إعدادات بيئة Microsoft Azure Active Directory B2C.

ASP.NET Core

في shell command، ابدأ تطبيق الويب عن طريق تشغيل الأمر التالي:

 dotnet run

يجب أن ترى الناتج التالي، مما يعني أن تطبيقك يعمل وأنه جاهز لتلقي الطلبات.

Now listening on: http://localhost:6000

لإيقاف البرنامج، في غلاف الأوامر، حدد Ctrl + C. يمكنك إعادة تشغيل التطبيق باستخدام الأمرnode app.js.

تلميح

بدلاً من ذلك، لتشغيل dotnet runالأمر، يمكنك استخدام مصحح رمز Visual Studio. يساعد مصحح الأخطاء المدمج في Visual Studio Code على تسريع حلقة التحرير والترجمة والتصحيح.

افتح مستعرضاً وانتقل إلى http://localhost:6000/public. في نافذة المتصفح، سترى النص التالي معروضًا مع التاريخ والوقت الحاليين.

Node.js

في shell command، ابدأ تطبيق الويب عن طريق تشغيل الأمر التالي:

node app.js

يجب أن ترى الناتج التالي، مما يعني أن تطبيقك يعمل وأنه جاهز لتلقي الطلبات.

Example app listening on port 6000!

لإيقاف البرنامج، في غلاف الأوامر، حدد Ctrl + C. يمكنك إعادة تشغيل التطبيق باستخدام الأمرnode app.js.

تلميح

بدلاً من ذلك، لتشغيلnode app.jsالأمر، استخدم مصحح رمز Visual Studio. يساعد مصحح الأخطاء المدمج في Visual Studio Code على تسريع حلقة التحرير والترجمة والتصحيح.

افتح مستعرضاً وانتقل إلى http://localhost:6000/public. في نافذة المتصفح، سترى النص التالي معروضًا مع التاريخ والوقت الحاليين.

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

حاول الاتصال بنقطة نهاية واجهة برمجة تطبيقات الويب المحمية بدون رمز وصول. افتح مستعرضاً وانتقل إلى http://localhost:6000/hello. ستعيد واجهة برمجة التطبيقات رسالة خطأ HTTP غير مصرح بها، تؤكد أن واجهة برمجة تطبيقات الويب محمية برمز حامل.

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

شاهد هذا الفيديو للتعرف على بعض أفضل الممارسات عند دمج Microsoft Azure Active Directory B2C مع واجهة برمجة التطبيقات.

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

احصل على المثال الكامل على GitHub:

ASP.NET Core

• احصل على واجهة برمجة تطبيقات الويب باستخدام مكتبة هوية Microsoft.

Node.js

• احصل على واجهة برمجة تطبيقات الويب باستخدام مكتبة Passport.js.