Вызов веб-API ASP.NET Core с помощью cURL

Статья
03/06/2025

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

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

Предварительные условия

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

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

Регистрация приложения в платформе идентификации Microsoft

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

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

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

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

Примечание.

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

Сделать API доступным

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

В разделе Управление выберите Сделать API доступным > Добавить область действия. Примите предлагаемый URI идентификатора приложения, выбрав Сохранить и продолжить. Значение {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. Убедитесь, что для состояния задано значение "Включено".
Выберите Добавить область. Если область введена правильно, она указана в панели "Expose an API".

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

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

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

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

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

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

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

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

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

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

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

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

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

В области Обзор веб-приложения (web-app-that-calls-web-api) в разделе Управление выберите Разрешения API, Добавить разрешение, API, которые использует моя организация.
Выберите NewWebAPI1 или API, к которому требуется добавить разрешения.
В поле Выбор разрешений установите флажок рядом с Прогноз.Чтение. Возможно, потребуется расширить список полномочий . Это определяет разрешения, которые клиентское приложение должно иметь от лица пользователя, вошедшего в систему.
Чтобы завершить процесс, выберите Добавление разрешений.

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

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

Тестирование веб-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 и откройте файл ./appsettings.json, замените {APPLICATION_CLIENT_ID} и {DIRECTORY_TENANT_ID}.
- {APPLICATION_CLIENT_ID} — это идентификатор приложения (клиента) для веб-API в области Обзор в Регистрация приложений.
- {DIRECTORY_TENANT_ID} — это идентификатор каталога (арендатора) веб API в области ОбзорРегистрация приложений приложения.
Выполните следующую команду, чтобы запустить приложение:
- .NET 6.0
- .NET 7.0
```
dotnet run
```
```
dotnet run --launch-profile https
```
Будут отображаться выходные данные, аналогичные приведенным ниже. Запишите номер порта в URL-адресе https://localhost:{port} .
```
... 
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

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

Перейдите к веб-API, созданному в руководстве: создайте проект ASP.NET Core и настройте API, например NewWebAPILocal, и откройте папку.
Откройте новое окно терминала и перейдите в папку, в которой находится проект веб-API.

.NET 6.0
.NET 7.0

Выполните следующую команду, чтобы запустить приложение:
```
dotnet run
```

Будут отображаться выходные данные, аналогичные приведенным ниже. Запишите номер порта в URL-адресе https://localhost:{port} .
```
... 
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...
```

Запрос кода авторизации

Поток кода авторизации начинается с того, что клиент направляет пользователя к конечной точке /authorize . В этом запросе клиент запрашивает Forecast.Read разрешение от пользователя.

https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/authorize?client_id={web-app-calls-web-api_application_client_id}&response_type=code&redirect_uri=http://localhost&response_mode=query&scope=api://{web_API_application_client_id}/Forecast.Read

Скопируйте URL-адрес, замените следующие параметры и вставьте его в браузер:
- {tenant_id} — это идентификатор каталога (тенанта) веб-приложения .
- {web-app-calls-web-api_application_client_id} — это идентификатор приложения (клиента) на панели Обзор веб-приложения (web-app-calls-web-api).
- {web_API_application_client_id} — это идентификатор приложения (клиента) на вкладке Обзор веб-API (NewWebAPI1).
Войдите в качестве пользователя в клиенте Microsoft Entra, в котором зарегистрированы приложения. При необходимости согласиться на любые запросы на доступ.
Браузер перенаправляется на http://localhost/. Перейдите на панель навигации браузера и скопируйте элемент {authorization_code}, чтобы использовать в следующих шагах. URL-адрес имеет форму следующего фрагмента кода:
```
http://localhost/?code={authorization_code}
```

Использование кода авторизации и cURL для получения токена доступа

Теперь cURL можно использовать для запроса токена доступа на платформе удостоверений Microsoft.

Скопируйте команду cURL в следующем фрагменте кода. Замените значения в скобках следующими параметрами в терминале. Не забудьте удалить скобки:
- Bash
- Командная строка Windows
```
curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token \
-d 'client_id={web-app-calls-web-api_application_client_id}' \
-d 'api://{web_API_application_client_id}/Forecast.Read' \
-d 'code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}' \
-d 'redirect_uri=http://localhost' \
-d 'grant_type=authorization_code' \
-d 'client_secret={client_secret}'
```
```
curl -X POST https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token ^
 -d "client_id={web-app-calls-web-api_application_client_id}" ^
 -d "api://{web_API_application_client_id}/Forecast.Read" ^
 -d "code={authorization_code}&session_state={web-app-calls-web-api_application_client_id}" ^
 -d "redirect_uri=http://localhost" ^
 -d "grant_type=authorization_code" ^
 -d "client_secret={client_secret}"
```
- {tenant_id}— это идентификатор каталога веб-приложения (клиента).
- , а — это идентификатор приложения (клиента) на панели Обзор веб-приложения (web-app-calls-web-api).
- api://{web_API_application_client_id}/Forecast.Read — это идентификатор приложения (клиента) на панели Обзор веб-API (NewWebAPI1).
- code={authorization_code} — код авторизации, полученный в запросе кода авторизации. Это позволяет средству cURL запрашивать маркер доступа.
- client_secret={client_secret}— значение секрета клиента, записанное в разделе "Добавление секрета клиента".
Выполните команду cURL и при правильном вводе необходимо получить ответ JSON, аналогичный следующим выходным данным:
```
{
   "token_type": "Bearer",
   "scope": "api://{web_API_application_client_id}/Forecast.Read",
   "expires_in": 3600,
   "ext_expires_in": 3600,
   "access_token": "{access_token}"
}
```

Вызов веб-API с токеном доступа

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

Чтобы вызвать веб-API, скопируйте следующую команду cURL, замените следующие значения в скобках и вставьте его в терминал:
```
curl -X GET https://localhost:{port}/weatherforecast -ki \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer {access_token}"
```
- {access_token} Значение маркера доступа, записанное из выходных данных JSON в предыдущем разделе.
- {port} номер порта из веб-API, записанный при запуске API в терминале. Убедитесь, что это номер порта https.

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

HTTP/2 200
content-type: application/json; charset=utf-8
date: Day, DD Month YYYY HH:MM:SS
server: Kestrel
[{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":36,"summary":"Hot","temperatureF":96},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":43,"summary":"Warm","temperatureF":109},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":18,"summary":"Warm","temperatureF":64},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":50,"summary":"Chilly","temperatureF":121},{"date":"YYYY-MM-DDTHH:MM:SS","temperatureC":3,"summary":"Bracing","temperatureF":37}]

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

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

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

Вызов веб-API ASP.NET Core с помощью cURL

Предварительные условия

Регистрация приложения в платформе идентификации Microsoft

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

Сделать API доступным

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

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

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

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

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

Запрос кода авторизации

Использование кода авторизации и cURL для получения токена доступа

Вызов веб-API с токеном доступа

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

Обратная связь

Дополнительные ресурсы