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

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

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

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

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

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

Регистрация приложения с помощью платформы удостоверений Майкрософт

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

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

Совет

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

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

1. Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.

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

3. Перейдите к приложениям> удостоверений>Регистрация приложений.

4. Выберите Создать регистрацию.

5. Введите имя приложения, например NewWebAPI1.

6. Для параметра Поддерживаемые типы учетных записей выберите Учетные записи только в этом каталоге организации. Для получения сведений о различных типах учетных записей выберите параметр "Справка".

7. Выберите Зарегистрировать.

   

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

   

Примечание.

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

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

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

1. В разделе "Управление" выберите "Предоставить 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. Убедитесь, что для состояния задано значение "Включено".

2. Выберите Добавить область. Если область введен правильно, он будет указан в области предоставления API.

   

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

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

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

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

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

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

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

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

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

1. В области "Обзор" в разделе "Управление" выберите "Сертификаты" и "Секреты>клиента">"Создать секрет клиента".

2. Добавьте описание секрета клиента, например "Мой секрет клиента".

3. Выберите срок действия секрета или укажите настраиваемое время существования.

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

4. Выберите Добавить.

5. Обязательно запишите значение секрета клиента. Это значение секрета больше нигде не отображается после закрытия страницы.

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

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

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

1. В области "Обзор" веб-приложения (веб-app-that-calls-web-api) в разделе "Управление" выберите разрешения API "Добавить разрешение>>"Мои API".
2. Выберите NewWebAPI1 или API, к которому требуется добавить разрешения.
3. В разделе "Выбор разрешений" проверка поле рядом с параметром Forecast.Read. Возможно, потребуется развернуть список разрешений . При выборе разрешений клиентское приложение должно быть от имени пользователя, вошедшего в систему.
4. Чтобы завершить процесс, выберите Добавление разрешений.

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

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

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

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

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

2. Перейдите в папку ms-identity-docs-code-dotnet/web-api и откройте ./appsettings.json файл, замените {APPLICATION_CLIENT_ID} его и {DIRECTORY_TENANT_ID} :

   • {APPLICATION_CLIENT_ID}— это идентификатор приложения веб-API (клиента) в области обзора приложения Регистрация приложений.
   • {DIRECTORY_TENANT_ID}— это идентификатор каталога веб-API (клиента) в области обзора приложения Регистрация приложений.

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

   .NET 6.0

   dotnet run
   

   .NET 7.0

   dotnet run --launch-profile https
   

4. Будут отображаться выходные данные, аналогичные приведенным ниже. Запишите номер порта в URL-адресе https://localhost:{port} .

   ... 
   info: Microsoft.Hosting.Lifetime[14]
         Now listening on: https://localhost:{port}
   ...
   

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

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

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

.NET 6.0

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

   dotnet run
   

.NET 7.0

1. Выполните следующую команду, чтобы запустить приложение в https профиле:

   dotnet run --launch-profile https
   

1. Будут отображаться выходные данные, аналогичные приведенным ниже. Запишите номер порта в 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

1. Скопируйте URL-адрес, замените следующие параметры и вставьте его в браузер:

   • {tenant_id}— это идентификатор каталога веб-приложения (клиента).
   • {web-app-calls-web-api_application_client_id}— это идентификатор приложения (клиента) в области обзора веб-приложения (web-app-calls-web-api).
   • {web_API_application_client_id}— это идентификатор приложения (клиента) в области обзора веб-API (NewWebAPI1).

2. Войдите в качестве пользователя в клиенте Microsoft Entra, в котором зарегистрированы приложения. При необходимости согласиться на любые запросы на доступ.

3. Браузер будет перенаправлен в http://localhost/. Перейдите на панель навигации браузера и скопируйте его {authorization_code} , выполнив указанные ниже действия. URL-адрес имеет форму следующего фрагмента кода:

   http://localhost/?code={authorization_code}
   

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

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

1. Скопируйте команду cURL в следующем фрагменте кода. Замените значения в скобках следующими параметрами в терминале. Не забудьте удалить скобки:

   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}— это идентификатор каталога веб-приложения (клиента).
   • client_id={web-app-calls-web-api_application_client_id}, и session_state={web-app-calls-web-api_application_client_id} является идентификатором приложения (клиента) в области обзора веб-приложения (web-app-calls-web-api).
   • api://{web_API_application_client_id}/Forecast.Read— это идентификатор приложения (клиента) в области обзора веб-API (NewWebAPI1).
   • code={authorization_code} — код авторизации, полученный в запросе кода авторизации. Это позволяет средству cURL запрашивать маркер доступа.
   • client_secret={client_secret}— значение секрета клиента, записанное в разделе "Добавление секрета клиента".

2. Выполните команду 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.

1. Чтобы вызвать веб-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 что это номер порта.

2. При наличии допустимого маркера доступа, включенного в запрос, ожидаемый ответ содержит 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 и типах приложений см. в следующих примерах:

• Поток кода авторизации OAuth 2.0 и платформа удостоверений Майкрософт
• Типы приложений для платформы удостоверений Майкрософт