Включение проверки подлинности в собственном веб-API с помощью Azure AD B2C

Чтобы авторизовать доступ к веб-API, можно обслуживать только запросы, содержащие допустимый маркер доступа, который возникает с проблемами Azure Active Directory B2C (Azure AD B2C). В этой статье показано, как включить авторизацию Azure AD B2C для веб-API. После выполнения действий, описанных в этой статье, вызывать конечные точки веб-API будет разрешено только пользователям, получившим действительный маркер доступа.

Необходимые компоненты

Прежде чем начать, прочитайте одну из следующих статей, в которых обсуждается настройка проверки подлинности для приложений, вызывающих веб-API. Затем выполните действия, описанные в этой статье, заменив взятый для примера веб-API на собственный веб-API.

• Настройка проверки подлинности в примере приложения ASP.NET Core
• Настройка проверки подлинности в примере одностраничного приложения

Обзор

Проверка подлинности на основе маркеров гарантирует, что запросы к веб-API включают допустимый маркер доступа.

Приложение выполняет следующие действия.

1. Выполняет проверку подлинности пользователей с помощью Azure AD B2C.

2. Получает маркер доступа с необходимыми разрешениями (областями) для конечной точки веб-API.

3. Передает маркер доступа как маркер носителя в заголовке авторизации HTTP-запроса, используя следующий формат:

   Authorization: Bearer <access token>
   

Веб-API выполняет следующие действия.

1. Считывает маркер носителя из заголовка авторизации в HTTP-запросе.

2. Проверяет маркер.

3. Проверяет разрешения (области) в маркере.

4. Считывает утверждения, которые кодируются в маркере (необязательно).

5. Отвечает на HTTP-запрос.

Обзор регистрации приложений

Чтобы включить вход приложения в Azure AD B2C и вызвать веб-API, необходимо зарегистрировать два приложения в каталоге Azure AD B2C.

• Регистрация мобильного, одностороннего или веб- приложения позволяет приложению выполнять вход с помощью Azure AD B2C. В процессе регистрации приложения создается идентификатор приложения, который также называется идентификатором клиента. Он однозначно идентифицирует ваше приложение (например, идентификатор приложения: 1).

• После регистрации веб-API приложение сможет совершать вызовы к защищенному веб-API. После регистрации станут доступны разрешения (области) веб-API. В процессе регистрации приложения система создает идентификатор приложения, с помощью которого можно уникальным образом идентифицировать ваш веб-API (например, идентификатор приложения: 2). Предоставьте своему приложению (с идентификатором приложения App ID 1) разрешения для областей веб-API (с идентификатором приложения App ID 2).

Регистрации приложений и архитектура приложений описаны на следующей схеме:

Подготовка среды разработки

В следующих разделах вы создадите проект веб-API. Выберите язык программирования: ASP.NET Core или Node.js. Убедитесь, что у вас есть компьютер, работающий под управлением любого из следующих программ:

ASP.NET Core

• Visual Studio Code
• C# для Visual Studio Code (последняя версия)
• Пакет SDK для .NET 5.0

Node.js

• Visual Studio Code или любой другой редактор кода.
• Среда выполнения Node.js.

Шаг 1. Создание защищенного веб-API

Создайте новый проект веб-API. Сначала выберите язык программирования, которые вы хотите использовать: ASP.NET Core или Node.js.

ASP.NET Core

Используйте команду dotnet new. Команда dotnet new создает новую папку с именем TodoList с ресурсами проекта веб-API. Откройте каталог, а затем откройте Visual Studio Code.

dotnet new webapi -o TodoList
cd TodoList
code . 

При появлении запроса "Добавьте необходимые ресурсы в проект" выберите Да.

Node.js

Используйте Экспресс для Node.js для создания веб-API. Чтобы создать веб-API, выполните следующие действия.

1. Создайте папку с именем TodoList.
2. В папке TodoList создайте файл с именем app.js.
3. В командной оболочке выполните команду npm init -y. Эта команда создает файл по умолчанию package.json для вашего проекта Node.js.
4. В командной оболочке запустите npm install express. Эта команда устанавливает платформу Express.

Шаг 2. Установка зависимостей

Добавьте библиотеку проверки подлинности в проект веб-API. Библиотека проверки подлинности анализирует заголовок проверки подлинности 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. Добавление конечных точек

Добавьте две конечные точки в веб-API:

• Анонимная конечная точка /public. Эта конечная точка возвращает текущие дату и время. Используйте ее для отладки веб-API с анонимными вызовами.
• Защищенная конечная точка /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 проверяет, вызывается ли веб-API из правильных областей, 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(). Функция проверки подлинности ограничивает доступ, предоставляя его только пользователям, прошедшим проверку подлинности.

Функция проверки подлинности также проверяет, вызывается ли веб-API из правильных областей. Разрешенные области находятся в файле конфигурации.

Шаг 5. Настройка веб-сервера

В среде разработки настройте веб-API для ожидания передачи данных через порт входящих HTTP- или HTTPS-запросов. В этом примере используйте порт HTTP 6000 и порт HTTPS 6001. Базовым универсальным кодом ресурса (URI) веб-API будет 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. Настройка веб-API

Добавьте конфигурации в файл конфигурации. Он содержит сведения о вашем поставщике удостоверений Azure AD B2C. Приложение веб-API использует эти сведения для проверки маркера доступа, который передает веб-приложение в качестве маркера носителя.

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	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 измените следующие свойства:

Раздел	Ключ	Значение
учетные данные	tenantName	Полное имя клиента/доменное имя Azure AD B2C (например, contoso.onmicrosoft.com).
учетные данные	clientID	Идентификатор приложения веб-API На предыдущей схеме это приложение с идентификатором 2. Сведения о том, как получить идентификатор регистрации приложения веб-API, см. в разделе Предварительные требования.
учетные данные	Издатель	Значение утверждения 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.
политики	policyName	Потоки пользователей или настраиваемая политика. Сведения о том, как получить поток пользователей или политику, см. в разделе Предварительные требования.
resource	область	Области регистрации приложения веб-API. Сведения о том, как узнать область своего веб-API, см. в разделе Предварительные требования.

Шаг 7. Запуск и тестирование веб-API

Наконец, запустите веб-API с параметрами среды Azure AD B2C.

ASP.NET Core

В командной оболочке запустите веб-приложение, выполнив следующую команду:

 dotnet run

Вы должны увидеть следующие выходные данные. Это будет означает, что приложение работает и готово к получению запросов.

Now listening on: http://localhost:6000

Чтобы остановить выполнение программы, в командной оболочке нажмите клавиши CTRL + C. Повторно запустить приложение можно с помощью команды node app.js.

Совет

Кроме того, для выполнения команды dotnet run можно использовать отладчик Visual Studio Code. Встроенный отладчик Visual Studio Code помогает ускорить цикл редактирования, компиляции и отладки.

Откройте веб-браузер и перейдите по адресу http://localhost:6000/public. В окне браузера должен отобразиться следующий текст, а также текущие дата и время.

Node.js

В командной оболочке запустите веб-приложение, выполнив следующую команду:

node app.js

Вы должны увидеть следующие выходные данные. Это будет означает, что приложение работает и готово к получению запросов.

Example app listening on port 6000!

Чтобы остановить выполнение программы, в командной оболочке нажмите клавиши CTRL + C. Повторно запустить приложение можно с помощью команды node app.js.

Совет

Кроме того, для выполнения команды node app.js можно использовать отладчик Visual Studio Code. Встроенный отладчик Visual Studio Code помогает ускорить цикл редактирования, компиляции и отладки.

Откройте веб-браузер и перейдите по адресу http://localhost:6000/public. В окне браузера должен отобразиться следующий текст, а также текущие дата и время.

Шаг 8. Вызов веб-API из приложения

Попробуйте вызвать защищенную конечную точку веб-API без маркера доступа. Откройте веб-браузер и перейдите по адресу http://localhost:6000/hello. API вернет сообщение об ошибке из-за неавторизованного HTTP. Это будет подтверждением того, что веб-API защищен с помощью маркера носителя.

Продолжайте настройку приложения для вызова веб-API. Указания см. в разделе Предварительные требования.

Просмотрите это видео, чтобы узнать о рекомендациях по интеграции Azure AD B2C с API.

Следующие шаги

Полный пример доступен на GitHub:

ASP.NET Core

• Получите веб-API, используя библиотеку идентификаторов Microsoft.

Node.js

• Получите веб-API, используя библиотеку Passport.js.