Вызов веб-API ASP.NET Core с бессонницей

Статья
05/22/2024

В этой статье показано, как вызвать защищенный веб-API ASP.NET Core с помощью бессонницы. Бессонница — это приложение, которое позволяет отправлять HTTP-запросы в веб-API для проверки политик авторизации и контроля доступа (проверки подлинности). В этой статье описано, как зарегистрировать веб-приложение и веб-API в клиенте. Веб-приложение используется для получения маркера доступа, созданного платформа удостоверений Майкрософт. Затем вы используете маркер для выполнения авторизованного вызова веб-API с помощью бессонницы.

В этой статье показано, как вызвать защищенный веб-API ASP.NET Core с помощью бессонницы. Бессонница — это приложение, которое позволяет отправлять HTTP-запросы в веб-API для проверки политик авторизации и контроля доступа (проверки подлинности). Далее из руководства. Реализация защищенной конечной точки в API, в которой вы создали защищенный API, необходимо зарегистрировать веб-приложение с помощью платформа удостоверений Майкрософт для создания маркера доступа. Затем вы используете маркер для выполнения авторизованного вызова API с помощью бессонницы.

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

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Эта учетная запись Azure должна иметь разрешения на управление приложениями. Любые из следующих ролей Microsoft Entra включают необходимые разрешения:
- Администратор приложений
- Разработчик приложения
- Администратор облачных приложений
Скачайте и установите бессонницу. Вы используете бессонницу для получения маркера доступа для запросов API.
Минимальное требование пакета SDK для .NET 8.0.

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Эта учетная запись Azure должна иметь разрешения на управление приложениями. Любые из следующих ролей Microsoft Entra включают необходимые разрешения:
- Администратор приложений
- Разработчик приложения
- Администратор облачных приложений
Завершение серии учебников:
Скачайте и установите бессонницу.

Регистрация приложения

Платформа удостоверений Майкрософт требует, чтобы ваше приложение было зарегистрировано перед предоставлением служб управления удостоверениями и доступом. Регистрация приложения позволяет указать имя и тип приложения и аудиторию входа. Аудитория входа указывает учетные записи пользователей, которым разрешен доступ к данному приложению.

Регистрация веб-API

Совет

Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.

Выполните следующие действия, чтобы создать регистрацию веб-API:

Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.
Если у вас есть доступ к нескольким клиентам, используйте значок "Параметры" в верхнем меню, чтобы переключиться на клиент, в котором вы хотите зарегистрировать приложение из меню каталогов и подписок.
Перейдите к приложениям> удостоверений>Регистрация приложений.
Выберите Создать регистрацию.
Введите имя приложения, например NewWebAPI1.
Для параметра Поддерживаемые типы учетных записей выберите Учетные записи только в этом каталоге организации. Для получения сведений о различных типах учетных записей выберите параметр "Справка".
Выберите Зарегистрировать.
При завершении регистрации вы увидите панель обзора приложения. Запишите идентификатор каталога (клиента) и идентификатор приложения (клиента), который будет использоваться в последующих шагах.

Примечание.

Поддерживаемые типы учетных записей можно изменить, ссылаясь на изменение учетных записей, поддерживаемых приложением.

Предоставление API

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

В разделе "Управление" выберите "Предоставить область" API > "Добавить область". Примите предлагаемый URI (api://{clientId}) идентификатора приложения, нажав кнопку "Сохранить" и продолжить. Значение {clientId} , записанное на странице обзора . Затем введите следующие сведения:
1. В поле Имя области введите Forecast.Read.
2. Убедитесь, что для параметра Кто может давать согласие выбран вариант Admins and users (Администраторы и пользователи).
3. В поле Отображаемое имя согласия администратора введите Read forecast data.
4. В поле Описание согласия администратора введите Allows the application to read weather forecast data.
5. В поле Отображаемое имя согласия пользователя введите Read forecast data.
6. В поле Описание согласия пользователя введите Allows the application to read weather forecast data.
7. Убедитесь, что для состояния задано значение "Включено".
Выберите Добавить область. Если область введена правильно, она отображается в области предоставления API .

Регистрация веб-приложения

Недостаточно иметь веб-API, вам также нужно веб-приложение для получения маркера доступа для доступа к веб-API.

Чтобы зарегистрировать веб-приложение, выполните следующие действия:

Выберите "Главная", чтобы вернуться на домашнюю страницу. Перейдите к приложениям> удостоверений>Регистрация приложений.
Выберите Создать регистрацию.
Введите имя приложения, например web-app-calls-web-api.
Для параметра Поддерживаемые типы учетных записей выберите Учетные записи только в этом каталоге организации. Для получения сведений о различных типах учетных записей выберите параметр "Справка ".
В разделе URI перенаправления (необязательно) выберите веб-сайт и введите http://localhost текстовое поле URL-адреса.
Выберите Зарегистрировать.

Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.
Если у вас есть доступ к нескольким клиентам, используйте значок "Параметры" в верхнем меню, чтобы переключиться на клиент, в котором вы хотите зарегистрировать приложение из меню каталогов и подписок.
Перейдите к приложениям> удостоверений>Регистрация приложений.
Выберите Создать регистрацию.
Введите имя приложения, например web-app-calls-web-api.
Для параметра Поддерживаемые типы учетных записей выберите Учетные записи только в этом каталоге организации. Для получения сведений о различных типах учетных записей выберите параметр "Справка ".
В разделе URI перенаправления (необязательно) выберите веб-сайт и введите http://localhost текстовое поле URL-адреса.
Выберите Зарегистрировать.

При завершении регистрации вы увидите панель обзора приложения. Запишите идентификатор каталога (клиента) и идентификатор приложения (клиента), который будет использоваться в последующих шагах.

Добавление секрета клиента

Секрет клиента — это строковое значение, которое приложение может использовать для идентификации себя и иногда называется паролем приложения. Веб-приложение использует секрет клиента, чтобы подтвердить свое удостоверение при запросе маркеров.

Выполните следующие действия, чтобы настроить секрет клиента:

В области "Обзор" в разделе "Управление" выберите "Сертификаты" и "Секреты>клиента">"Создать секрет клиента".
Добавьте описание секрета клиента, например "Мой секрет клиента".
Выберите срок действия секрета или укажите настраиваемое время существования.
- Срок жизни секрета клиента ограничен двумя годами (24 месяцами) или меньше. Для настраиваемого времени существования нельзя задать значение, превышающее 24 месяца.
- Корпорация Майкрософт рекомендует задать значение срока действия менее 12 месяцев.
Выберите Добавить.
Обязательно запишите значение секрета клиента. Это значение секрета больше нигде не отображается после закрытия страницы.

Дополнительные сведения о безопасном хранении секрета клиента см. в рекомендациях по управлению секретами в Key Vault.

Добавление разрешений для доступа к веб-API

Указав области веб-API, веб-приложение может получить маркер доступа, содержащий области, предоставляемые платформа удостоверений Майкрософт. В коде веб-API может предоставить доступ на основе разрешений к своим ресурсам на основе областей, найденных в маркере доступа.

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

В области "Обзор" приложения в разделе "Управление" выберите разрешения API", чтобы добавить API разрешений>>, которые используются моей организацией.
Выберите NewWebAPI1 или API, к которому требуется добавить разрешения.
В разделе "Выбор разрешений" установите флажок " Прогноз.Чтение". Возможно, потребуется развернуть список разрешений . При выборе разрешений клиентское приложение должно быть от имени пользователя, вошедшего в систему.
Чтобы завершить процесс, выберите Добавление разрешений.

После добавления этих разрешений в API вы увидите выбранные разрешения в разделе "Настроенные разрешения".

Вы также можете заметить разрешение User.Read для API Microsoft Graph. Это разрешение добавляется автоматически при регистрации приложения.

Тестирование веб-API

Чтобы убедиться, что API работает и готов к обработке запросов, выполните следующие действия.

Клонируйте репозиторий ms-identity-docs-code-dotnet .

git clone https://github.com/Azure-Samples/ms-identity-docs-code-dotnet.git

Перейдите к файлу ms-identity-docs-code-dotnet/web-api и {DIRECTORY_TENANT_ID} откройте appsettings.jsonего, замените {APPLICATION_CLIENT_ID} следующими значениями:
- {APPLICATION_CLIENT_ID}— это идентификатор приложения веб-API (клиента) на панели обзора приложения.
- {DIRECTORY_TENANT_ID}— это идентификатор каталога веб-API (клиента) на панели обзора приложения.
Выполните следующую команду, чтобы запустить приложение:
```
dotnet run
```
Будут отображаться выходные данные, аналогичные приведенным ниже. Запишите номер порта в URL-адресе https://localhost:{port} .
```
...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

Тестирование веб-API

Чтобы убедиться, что API работает и готов к обработке запросов, выполните следующие действия.

Перейдите к веб-API, созданному в руководстве: создайте проект ASP.NET Core и настройте API, например NewWebAPILocal, и откройте папку.
Откройте новое окно терминала и перейдите в папку, в которой находится проект веб-API.
- .NET 6.0
- .NET 7.0
1. Выполните следующую команду, чтобы запустить приложение:
```
dotnet run
```
1. Откройте новый терминал и выполните следующую команду, чтобы запустить приложение в https профиле:
```
dotnet run -launch-profile https`
```
Будут отображаться выходные данные, аналогичные приведенным ниже. Запишите номер порта в URL-адресе https://localhost:{port} .
```
...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

Настройка авторизованного запроса на веб-API в бессоннице

Чтобы получить маркер доступа для запросов API, выполните следующие действия.

Запустите приложение "Бессонница".
Выберите новый HTTP-запрос или нажмите клавиши CTRL+N для создания нового HTTP-запроса.
В модале нового запроса выберите метод GET из раскрывающегося списка.
Для URL-адреса запроса введите URL-адрес конечной точки, предоставляемой веб-API. https://localhost:{port}/weatherforecast
В раскрывающемся меню проверки подлинности выберите OAuth 2.0. Откроется форма OAuth 2.0 .

Введите следующие значения в форме OAuth 2.0 :

Параметр	Значение
ТИП GRANT	Выбор кода авторизации
URL-адрес АВТОРИЗАЦИИ	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize` Замените `{tenantId}` идентификатором каталога (клиента)
URL-АДРЕС МАРКЕРА ДОСТУПА	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token` Замена `{tenantId}` идентификатором каталога (клиента)
ИДЕНТИФИКАТОР КЛИЕНТА	Значение идентификатора приложения (клиента) регистрации веб-приложения
СЕКРЕТ КЛИЕНТА	Значение секрета клиента регистрации веб-приложения
URL-АДРЕС ПЕРЕНАПРАВЛЕНИЯ	Введите `http://localhost`, который задает URL-адрес ПЕРЕНАПРАВЛЕНия для URI перенаправления, зарегистрированного с идентификатором Microsoft Entra.
Область расширенных параметров>	`api://{application_client_id}/Forecast.Read` Перейдите к регистрации веб-приложения в разделе "Управление", выберите разрешения API, а затем выберите "Прогноз.Чтение". Скопируйте значение в текстовое поле, содержащее значение Scope

Получение маркера доступа и отправка запроса в веб-API

После ввода этих значений выберите маркеры получения в конце формы. Откроется окно браузера "Бессонница", где выполняется проверка подлинности с помощью учетных данных пользователя. Не забудьте разрешить всплывающие окна из приложения "Бессонница" в браузере.
После проверки подлинности выберите "Отправить ", чтобы отправить запрос в конечную точку защищенного веб-API.

При наличии допустимого маркера доступа, включенного в запрос, ожидаемый ответ равен 200 ОК с выходными данными, аналогичными:

[
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": -16,
    "summary": "Scorching",
    "temperatureF": 4
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 1,
    "summary": "Sweltering",
    "temperatureF": 33
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 26,
    "summary": "Freezing",
    "temperatureF": 78
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 54,
    "summary": "Mild",
    "temperatureF": 129
  },
  {
    "date": "YYYY-MM-DDTHH:MM:SS",
    "temperatureC": 11,
    "summary": "Bracing",
    "temperatureF": 51
  }
]

Дополнительные сведения о потоке кода авторизации oAuth 2.0 и типах приложений см. в следующих примерах:

Поделиться через

Вызов веб-API ASP.NET Core с бессонницей

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