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

هام

اعتبارا من 1 مايو 2025، لن يكون Azure AD B2C متوفرا للشراء للعملاء الجدد. تعرف على المزيد في الأسئلة المتداولة.

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

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

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

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

نظرة عامة

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

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

1. وهو يصادق المستخدمين باستخدام Azure AD B2C.

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

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

   Authorization: Bearer <access token>
   

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

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

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

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

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

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

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

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

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

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

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

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

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

ASP.NET Core

• Visual Studio Code
• C# ل 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

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

1. إنشاء مجلد جديد باسم TodoList.
2. ضمن المجلد TodoList ، أنشئ ملفا باسم app.js.
3. في أمر shell، قم بتشغيل npm init -y. ينشئ هذا الأمر ملف package.json افتراضيا لمشروعك 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")]. يتحقق RequiredScopeAttribute من استدعاء واجهة برمجة تطبيقات الويب مع النطاقات الصحيحة، 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. سيكون http://localhost:6000 عنوان URI الأساسي لواجهة برمجة تطبيقات الويب ل HTTP وHTTPS https://localhost:6001 .

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: تكوين واجهة برمجة تطبيقات الويب

إضافة تكوينات إلى ملف تكوين. يحتوي الملف على معلومات حول موفر هوية Azure AD 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	مثيل	الجزء الأول من اسم مستأجر Azure AD B2C (على سبيل المثال، https://contoso.b2clogin.com).
AzureAdB2C	المجال	اسم المستأجر الكامل لمستأجر Azure AD B2C (على سبيل المثال، contoso.onmicrosoft.com).
AzureAdB2C	معرف العميل	معرف تطبيق واجهة برمجة تطبيقات الويب. في الرسم التخطيطي السابق، إنه التطبيق مع معرف التطبيق: 2. لمعرفة كيفية الحصول على معرف تسجيل تطبيق واجهة برمجة تطبيقات الويب، راجع المتطلبات الأساسية.
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).
وثائق التفويض	معرف العميل	معرف تطبيق واجهة برمجة تطبيقات الويب. في الرسم التخطيطي السابق، إنه التطبيق مع معرف التطبيق: 2. لمعرفة كيفية الحصول على معرف تسجيل تطبيق واجهة برمجة تطبيقات الويب، راجع المتطلبات الأساسية.
وثائق التفويض	المصدر	قيمة مطالبة مصدر iss الرمز المميز. بشكل افتراضي، يقوم Azure AD B2C بإرجاع الرمز المميز بالتنسيق التالي: https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. استبدل <your-tenant-name> بالجزء الأول من اسم مستأجر Azure AD B2C. استبدل <your-tenant-ID>بمعرف مستأجر Azure AD B2C.
سياسات	اسم النهج	يتدفق المستخدم أو النهج المخصص. لمعرفة كيفية الحصول على تدفق المستخدم أو النهج، راجع المتطلبات الأساسية.
مورد	نطاق	نطاقات تسجيل تطبيق واجهة برمجة تطبيقات الويب. لمعرفة كيفية الحصول على نطاق واجهة برمجة تطبيقات الويب، راجع المتطلبات الأساسية.

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

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

ASP.NET Core

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

 dotnet run

يجب أن تشاهد الإخراج التالي، ما يعني أن تطبيقك قيد التشغيل وجاهز لتلقي الطلبات.

Now listening on: http://localhost:6000

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

تلميح

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

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

Node.js

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

node app.js

يجب أن تشاهد الإخراج التالي، ما يعني أن تطبيقك قيد التشغيل وجاهز لتلقي الطلبات.

Example app listening on port 6000!

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

تلميح

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

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

الخطوة 8: استدعاء واجهة برمجة تطبيقات الويب من تطبيقك

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

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

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

المحتوى ذو الصلة

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

ASP.NET Core

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

Node.js

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