Настройка проверки подлинности в примере веб-приложения, которое вызывает веб-API при помощи Azure AD B2C
В этой статье используется пример веб-приложения ASP.NET, вызывающего веб-API для демонстрации того, как добавить проверку подлинности Azure Active Directory B2C (Azure AD B2C) в веб-приложения.
Важно!
Пример веб-приложения ASP.NET, упомянутый в этой статье, используется для вызова веб-API с помощью маркера носителя. Дополнительные сведения о веб-приложении, которое не вызывает веб-API, см. в статье Настройка проверки подлинности в примере веб-приложения с помощью Azure AD B2C.
Обзор
OpenID Connect (OIDC) представляет собой протокол проверки подлинности, основанный на OAuth 2.0. OIDC можно использовать для безопасного входа пользователя в приложение. В этом примере веб-приложения используется Microsoft Identity Web. Microsoft Identity Web — это набор библиотек ASP.NET Core, которые упрощают процесс добавления проверки подлинности и авторизации в веб-приложения, которые могут вызывать безопасный веб-API.
Процесс входа включает следующие шаги:
Пользователи переходят к веб-приложению и выбирают Вход.
Приложение инициирует запрос на проверку подлинности и перенаправляет пользователей в Azure AD B2C.
Пользователи регистрируются или входят в систему и сбрасывают пароль. Либо они могут использовать для входа учетную запись социальной сети.
После входа пользователей Azure AD B2C возвращает приложению код авторизации.
Затем приложение выполняет следующие действия:
a. Обменивает код авторизации на маркер идентификатора, маркер доступа и маркер обновления.
b. Считывает утверждения маркера идентификатора и сохраняет файл cookie авторизации приложения.
c. Сохраняет маркер обновления в кэше в памяти для последующего использования.
Обзор регистрации приложений
Чтобы обеспечить вход в приложение с помощью Azure AD B2C и вызов веб-API, зарегистрируйте два приложения в каталоге Azure AD B2C.
Регистрация веб-приложения позволяет приложению выполнять вход с помощью Azure AD B2C. Во время регистрации вы указываете URI перенаправления. URI перенаправления — это конечная точка, в которую пользователи перенаправляются службой Azure AD B2C после завершения проверки подлинности с помощью Azure AD B2C. В процессе регистрации приложения создается идентификатор приложения, который также называется идентификатором клиента. Он однозначно идентифицирует ваше приложение. Кроме того, создается секрет клиента, который используется приложением для безопасного получения маркеров.
Регистрация веб-API позволяет приложению вызывать безопасный веб-API. Регистрация включает области веб-API. Области предоставляют возможностью управления разрешениями для защищенных ресурсов, например веб-API. Вы предоставляете веб-приложению разрешения для областей веб-API. При запросе маркера доступа приложению необходимо указать нужные разрешения в параметре scope запроса.
Архитектура и регистрация приложения показаны на следующей схеме:
Вызов веб-API
После завершения проверки подлинности пользователи взаимодействуют с приложением, которое вызывает защищенный веб-API. Этот веб-API использует проверку подлинности посредством маркера носителя. Маркер носителя — это маркер доступа, полученный приложением от Azure AD B2C. Приложение передает маркер в заголовке авторизации HTTPS-запроса.
Authorization: Bearer <access token>
Если область действия токена доступа не соответствует областям веб-API, библиотека аутентификации получает новый токен доступа с правильными областями.
Функция выхода
Поток выхода включает следующие шаги:
- В приложении пользователь выполняет выход.
- Приложение очищает объекты сеанса, а библиотека проверки подлинности очищает свой кэш маркеров.
- Приложение перенаправляет пользователя в конечную точку выхода Azure AD B2C, чтобы завершить сеанс Azure AD B2C.
- Пользователи перенаправляются обратно в приложение.
Необходимые компоненты
Компьютер, на котором работает:
- Visual Studio 2022 17.0 или более поздней версии с ASP.NET и рабочей нагрузкой веб-разработки
- Пакет SDK для .NET 6.0
Шаг 1. Настройка потока пользователя
Если пользователи пытаются войти в приложение, оно инициирует запрос проверки подлинности к конечной точке авторизации через поток пользователя. Соответствующий поток пользователя определяет и контролирует взаимодействие с пользователем. Когда пользователи завершают поток пользователя, Azure AD B2C создает маркер и перенаправляет пользователя обратно в приложение.
Создайте поток пользователя или пользовательскую политику, если вы еще не сделали этого. Повторите эти шаги, чтобы создать три отдельных пользовательских потока:
- Объединенный пользовательский поток входа и регистрации, например
susi. Этот пользовательский поток также поддерживает функцию Забыли пароль?. - Пользовательский поток редактирования профиля, например
edit_profile. - Пользовательский поток сброса пароля, например
reset_password.
Azure AD B2C добавляет B2C_1_ в начало имени пользовательского потока. Например, susi преобразуется в B2C_1_susi.
Шаг 2. Регистрация веб-приложения
На этом шаге вы создадите веб-приложение и регистрацию приложения веб-API, а также укажете области веб-API.
Шаг 2.1. Регистрация приложения веб-API
Чтобы создать регистрацию приложения веб-API (идентификатор приложения: 2), выполните следующие действия.
Войдите на портал Azure.
Убедитесь, что вы используете каталог, содержащий клиент Azure AD B2C. На панели инструментов портала выберите значок Каталоги и подписки.
В настройках портала на странице Каталоги и подписки найдите свой каталог Azure AD B2C в списке Имя каталога и выберите Переключить.
В портале Azure найдите и выберите Azure AD B2C.
Щелкните Регистрация приложений и выберите Новая регистрация.
В поле Имя введите имя приложения (например, my-api1). Оставьте значения по умолчанию для URI перенаправления и поддерживаемых типов учетных записей.
Выберите Зарегистрировать.
Когда регистрация приложения завершится, выберите Обзор.
Запишите значение идентификатора приложения (клиента) для дальнейшего использования при настройке веб-приложения.
Шаг 2.2. Настройка областей приложения веб-API
Выберите созданное приложение my-api1 (идентификатор приложения: 2), чтобы открыть страницу Обзор.
В разделе Управление выберите Предоставление API.
Рядом с полем URI идентификатора приложения щелкните ссылку Задать. Замените значение по умолчанию (уникальный идентификатор) уникальным именем (например, tasks-api), а затем нажмите Сохранить.
Когда веб-приложение запрашивает маркер доступа для веб-API, оно должно добавить этот URI в качестве префикса для каждой области, определяемой для API.
В разделе Области, определенные этим API выберите Добавление области.
Чтобы создать область, определяющую доступ для чтения к API, сделайте следующее.
- В поле Имя области введите tasks.read.
- В качестве отображаемого имени согласия администратора укажите Доступ на чтение к API задач.
- В качестве описания согласия администратора введите Предоставляет доступ на чтение к API задач.
Выберите Добавить область.
Выберите Добавить область и добавьте область, определяющую доступ для записи к API:
- В поле Имя области введите tasks.write.
- В качестве отображаемого имени согласия администратора укажите Доступ на запись к API задач.
- В качестве описания согласия администратора введите Предоставляет доступ на запись к API задач.
Выберите Добавить область.
Шаг 2.3. Регистрация веб-приложения
Чтобы создать регистрацию веб-приложения, сделайте следующее:
Щелкните Регистрация приложений и выберите Новая регистрация.
В поле Имя введите имя приложения (например, webapp1).
В области Поддерживаемые типы учетных записей выберите Учетные записи в любом поставщике удостоверений или в организационном каталоге (для аутентификации пользователей с помощью потока пользователей).
В поле URI перенаправления выберите Интернет и введите
https://localhost:5000/signin-oidcв поле URL-адреса.В разделе Разрешения установите флажок Предоставьте согласие администратора для разрешений openid и offline_access.
Выберите Зарегистрировать.
Когда регистрация приложения завершится, выберите Обзор.
Запишите значение параметра Идентификатор приложения (клиента) для использования на более позднем этапе при настройке веб-приложения.
Шаг 2.4. Создание секрета клиента веб-приложения
Создайте секрет клиента для зарегистрированного веб-приложения. Веб-приложение использует секрет клиента для подтверждения подлинности при запросе токенов.
- В разделе Управление выберите Сертификаты и секреты.
- Щелкните Создать секрет клиента.
- В поле Описание введите описание секрета клиента (например, clientsecret1).
- В разделе Истекает выберите срок действия секрета, а затем выберите Добавить.
- Запишите значение секрета в поле Значение. Это значение будет использовано позже для конфигурации.
Шаг 2.5. Предоставление веб-приложению разрешения для веб-API
Чтобы предоставить своему приложению (идентификатор приложения: 1) разрешения, выполните следующие действия.
Выберите Регистрация приложений, а затем выберите созданное вами приложение (идентификатор приложения: 1).
В разделе Управление выберите Разрешения API.
В разделе Настроенные разрешения выберите Добавить разрешение.
Выберите вкладку Мои API.
Выберите API (идентификатор приложения: 2), к которому веб-приложению должен быть предоставлен доступ. Например, введите my-api1.
В разделе Разрешение разверните узел tasks, а затем выберите определенные ранее области (например, tasks.read и tasks.write).
Выберите Добавить разрешения.
Выберите Предоставить согласие администратора для <имя арендатора>.
Выберите Да.
Выберите Обновить, а затем убедитесь, что Разрешено для... отображается в разделе Состояние для обеих областей.
В списке настроенных разрешений выберите свою область, а затем скопируйте полное имя области.
Шаг 3. Получение примера веб-приложения
Скачайте zip-файл или выполните следующую команду Bash, чтобы клонировать пример веб-приложения из GitHub.
git clone https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2
Извлеките предоставленный для примера файл в папку, где общая длина пути не превышает 260 символов.
Шаг 4. Настройка примера веб-API
В папке примера в разделе 4-WebApp-your-API/4-2-B2C/TodoListService откройте проект TodoListService.csproj с помощью Visual Studio или Visual Studio Code.
В корневой папке проекта откройте файл appsettings.json. Он содержит сведения о поставщике удостоверений Azure AD B2C. Приложение веб-API использует эти сведения для проверки маркера доступа, который передает веб-приложение в качестве маркера носителя. Обновите следующие свойства параметров приложения:
| Раздел | Ключ | Значение |
|---|---|---|
| AzureAdB2C | Экземпляр | Первая часть имени клиента Azure AD B2C. Например, https://contoso.b2clogin.com. |
| AzureAdB2C | Домен | Полное имя клиента Azure AD B2C. Например, contoso.onmicrosoft.com. |
| AzureAdB2C | ClientId | Идентификатор приложения веб-API из шага 2.1. |
| AzureAdB2C | SignUpSignInPolicyId | Потоки пользователей или настраиваемая политика из шага 1. |
Итоговый файл конфигурации должен выглядеть как следующий файл 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
}
Шаг 4.1. Настройка политики разрешений
Веб-API проверяет, прошел ли пользователь проверку подлинности с помощью маркера носителя, а также настроены ли допустимые области для маркера носителя. Если маркер носителя не имеет ни одной из этих допустимых областей, веб-API возвращает код состояния HTTP 403 (Запрещено) и записывает в текст ответа сообщение, указывающее, какие области ожидаются в маркере.
Чтобы настроить допустимые области, откройте класс Controller/TodoListController.cs и задайте имя области без полного универсального кода ресурса (URI).
[RequiredScope("tasks.read")]
Шаг 4.2. Запуск примера приложения веб-API
Чтобы разрешить веб-приложению вызов примера веб-API, запустите веб-API, выполнив следующие действия:
- Если вы получили соответствующий запрос, восстановите зависимости.
- Постройте и запустите проект.
- После создания проекта Visual Studio или Visual Studio Code запускает веб-API в браузерах со следующим адресом: https://localhost:44332..
Шаг 5. Настройка примера веб-приложения
В папке примера в разделе 4-WebApp-your-API/4-2-B2C/Client откройте проект TodoListClient.csproj с помощью Visual Studio или Visual Studio Code.
В корневой папке проекта откройте файл appsettings.json. Он содержит сведения о поставщике удостоверений Azure AD B2C. Веб-приложение использует эти сведения для установления с Azure AD B2C отношений доверия, входа и выхода пользователей, получения маркеров и их проверки. Обновите следующие свойства параметров приложения:
| Раздел | Ключ | Значение |
|---|---|---|
| AzureAdB2C | Экземпляр | Первая часть имени клиента Azure AD B2C (например, https://contoso.b2clogin.com). |
| AzureAdB2C | Домен | Полное имя клиента Azure AD B2C (например, contoso.onmicrosoft.com). |
| AzureAdB2C | ClientId | Идентификатор веб-приложения из шага 2.3. |
| AzureAdB2C | ClientSecret | Секрет веб-приложения из шага 2.4. |
| AzureAdB2C | SignUpSignInPolicyId | Потоки пользователей или настраиваемая политика из шага 1. |
| TodoList | TodoListScope | Области веб-API, созданные на шаге 2.5. |
| TodoList | TodoListBaseAddress | Базовый URI веб-API (например, https://localhost:44332). |
Итоговый файл конфигурации должен выглядеть как следующий файл JSON:
{
"AzureAdB2C": {
"Instance": "https://contoso.b2clogin.com",
"Domain": "contoso.onmicrosoft.com",
"ClientId": "<web-app-application-id>",
"ClientSecret": "<web-app-application-secret>",
"SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
"SignUpSignInPolicyId": "<your-sign-up-in-policy>"
},
"TodoList": {
"TodoListScope": "https://contoso.onmicrosoft.com/api/demo.read",
"TodoListBaseAddress": "https://localhost:44332"
}
}
Шаг 6. Запуск примера веб-приложения
- Постройте и запустите проект.
- Перейдите в
https://localhost:5000. - Завершите процесс регистрации или входа в систему.
После успешной проверки подлинности отображаемое имя появится в области навигации. Чтобы просмотреть утверждения, возвращаемые маркером Azure AD B2C в приложение, выберите TodoList.
Развертывание приложения
В рабочем приложении URI перенаправления регистрации приложения — это обычно общедоступная конечная точка, где выполняется приложение, например https://contoso.com/signin-oidc.
URI перенаправления в зарегистрированных приложениях можно добавлять и изменять в любое время. На URI перенаправления налагаются следующие ограничения.
- URL-адрес ответа должен начинаться со схемы
https. - В URL-адресе ответа учитывается регистр. Его регистр должен соответствовать регистру URL-пути выполняющегося приложения.
Кэш маркеров для веб-приложения
В примере веб-приложения используется сериализация кэша маркеров в памяти. Эта реализация отлично подходит для выборки. Она также хорошо подходит для рабочих приложений (если вы не против того, что при перезапуске веб-приложения кэш маркеров будет потерян).
Для рабочей среды мы рекомендуем использовать кэш распределенной памяти. Например, кэш Redis, NCache или кэш SQL Server. Дополнительные сведения о реализациях кэша распределенной памяти см. в статье Сериализация кэша маркеров.
Следующие шаги
- Узнайте больше о примере кода.
- Узнайте, как включить проверку подлинности в собственном веб-приложении с помощью Azure AD B2C.
- Узнайте, как включить проверку подлинности в собственном веб-API.