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

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

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

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

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

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

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

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

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

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

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

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

3. Перейдите к Entra ID>регистрации приложений.

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

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

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

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

   

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

   

Примечание.

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

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

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

1. В разделе "Управление" выберите "Опубликовать API" > "Добавить область". Выберите предлагаемый URI идентификатора приложения(api://{clientId}), нажав "Сохранить и продолжить". Значение {clientId}, зафиксированное со страницы Обзор. Затем введите следующие сведения:

   1. В поле "Имя области" введите Forecast.Read.
   2. Для того, кто может предоставить согласие, убедитесь, что выбран параметр "Администраторы и пользователи ".
   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. Выберите "Главная", чтобы вернуться на домашнюю страницу. Перейдите к Entra ID>регистрации приложений.
2. Выберите "Создать регистрацию".
3. Введите имя приложения, например web-app-calls-web-api.
4. Для поддерживаемых типов учетных записей выберите только учетные записи в этом каталоге организации. Для получения сведений о различных типах учетных записей выберите параметр «Помогите мне выбрать».
5. В разделе URI перенаправления (необязательно) выберите веб-сайт и введите http://localhost текстовое поле URL-адреса.
6. Выберите "Зарегистрировать".

1. Войдите в Центр администрирования Microsoft Entra как минимум разработчик приложений.
2. Если у вас есть доступ к нескольким клиентам, используйте значок "Параметры" в верхнем меню, чтобы переключиться на клиент, в котором вы хотите зарегистрировать приложение из меню каталогов и подписок.
3. Перейдите к Entra ID>регистрации приложений.
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. В области Обзор веб-приложения (web-app-that-calls-web-api) в разделе Управление выберите Разрешения API, Добавить разрешение, API, которые использует моя организация.
2. Выберите NewWebAPI1 или API, к которому требуется добавить разрешения.
3. В разделе Выбор разрешений установите флажок рядом с Прогноз.Чтение. Возможно, потребуется расширить список полномочий . Это определяет разрешения, которые клиентское приложение должно иметь от лица пользователя, вошедшего в систему.
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} — это Идентификатор каталога (арендатора) на панели Обзор приложения Регистрации приложений.

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 можно использовать для запроса токена доступа на платформе удостоверений Microsoft.

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}'
   

   Командная строка 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}"
   

   • {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} — значение секрета клиента, записанное в разделе "Добавление секрета клиента".

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
• Типы приложений для платформы удостоверений Майкрософт