Краткое руководство. Защита веб-API ASP.NET Core с помощью платформы удостоверений Майкрософт

Статья
10/24/2023

Добро пожаловать! Возможно, это не та страница, которую вы ожидали. Пока мы работаем над исправлением, воспользуйтесь этой ссылкой, чтобы перейти к нужной статье:

Краткое руководство. Вызов веб-API ASP.NET Core, защищенный платформа удостоверений Майкрософт

Приносим извинения за неудобства и благодарим за терпение! Мы работаем над устранением этой проблемы.

В следующем кратком руководстве используется пример кода веб-API ASP.NET Core для демонстрации ограничения доступа к ресурсам авторизованным учетным записям. Пример поддерживает авторизацию личных учетных записей Майкрософт и учетных записей в любой организации Microsoft Entra.

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

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Клиент Microsoft Entra
Минимальное требование пакета SDK для .NET 6.0
Visual Studio 2022 или Visual Studio Code

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

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

Войдите в Центр администрирования Microsoft Entra как минимум приложение Администратор istrator.
Перейдите к приложениям> удостоверений>Регистрация приложений.
Выберите Создать регистрацию.
Введите имя приложения Например, введите AspNetCoreWebApi-Quickstart. Пользователи приложения увидят это имя и могут быть изменены позже.
Выберите Зарегистрировать.
В разделе Управление выберите Предоставление API>Добавить группу. Примите URI идентификатора приложения по умолчанию, выбрав Сохранить и продолжить, а затем введите следующие сведения:

Имя области: access_as_user
Кто может предоставить согласие?: Администратор и пользователи
Отображаемое имя согласия администратора: Access AspNetCoreWebApi-Quickstart
Описание согласия администратора: Allows the app to access AspNetCoreWebApi-Quickstart as the signed-in user.
Отображаемое имя согласия пользователя: Access AspNetCoreWebApi-Quickstart
Описание согласия пользователя: Allow the application to access AspNetCoreWebApi-Quickstart on your behalf.
Состояние: включено

Выберите Добавить область, чтобы завершить добавление области.

Шаг 2. Скачивание проекта ASP.NET Core

Скачивание решения ASP.NET Core с сайта GitHub.

Примечание.

Пример кода в настоящее время предназначен для ASP.NET Core 3.1. Пример можно обновить для использования .NET Core 6.0 и описан в следующих шагах: обновите пример кода до ASP.NET Core 6.0. Это краткое руководство будет устарело в ближайшем будущем и будет обновлено для использования .NET 6.0.

Шаг 3. Настройка проекта ASP.NET Core

На этом шаге пример кода будет настроен для работы с регистрацией приложения, созданной ранее.

Извлеките файл .zip в локальную папку, близкую к корне диска, чтобы избежать ошибок, вызванных ограничениями длины пути в Windows. Например, извлеките в C:\Azure-Samples.
Откройте решение в папке webapi в редакторе кода.
В appsettings.json замените значения ClientIdи TenantId.
```
"ClientId": "Enter_the_Application_Id_here",
"TenantId": "Enter_the_Tenant_Info_Here"
```
- Enter_the_Application_Id_Here — это идентификатор приложения (клиента) для зарегистрированного приложения.
- Замените Enter_the_Tenant_Info_Here одним из следующих элементов:
  - Если приложение поддерживает учетные записи только в этом каталоге организации, замените это значение идентификатором каталога (клиента) (GUID) или именем клиента (например, contoso.onmicrosoft.com). Идентификатор каталога (клиента) можно найти на странице обзора приложения.
  - Если приложение поддерживает учетные записи в любом каталоге организации, замените это значение organizationsна .
  - Если приложение поддерживает всех пользователей учетной записи Майкрософт, оставьте это значение commonкак .

Для целей этого руководства изменение других значений в файле appsettings.json не требуется.

Шаг 4. Обновление примера кода до ASP.NET Core 6.0

Чтобы обновить этот пример кода для целевого ASP.NET Core 6.0, выполните следующие действия.

Открытие webapi.csproj
Удалите следующую строку:

<TargetFramework>netcoreapp3.1</TargetFramework>

Добавьте в его место следующую строку:

<TargetFramework>netcoreapp6.0</TargetFramework>

Этот шаг гарантирует, что пример предназначен для платформы .NET Core 6.0.

Шаг 5. Запуск примера

Откройте терминал и измените каталог в папку проекта.
```
cd webapi
```
Выполните следующую команду, чтобы создать решение:

dotnet run

Если сборка выполнена успешно, отображаются следующие выходные данные:

Building...
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: https://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Now listening on: http://localhost:{port}
info: Microsoft.Hosting.Lifetime[0]
    Application started. Press Ctrl+C to shut down.
...

Как работает этот пример

Класс Startup

ПО промежуточного слоя Microsoft.AspNetCore.Authentication использует класс Startup, который выполняется при запуске хост-процесса. В его методе ConfigureServices вызывается метод расширения AddMicrosoftIdentityWebApi, предоставленный Microsoft.Identity.Web.

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd");
    }

С помощью метода AddAuthentication() службу можно настроить так, чтобы она добавляла проверку подлинности на основе JwtBearer.

Строка, содержащая .AddMicrosoftIdentityWebApi платформа удостоверений Майкрософт авторизацию, добавляется в веб-API. Затем она настраивается для проверки маркеров доступа, созданных платформой удостоверений Майкрософт на основе сведений в разделе AzureAD файла конфигурации appsettings.json:

Ключ appsettings.json	Description
`ClientId`	Идентификатор приложения (клиента) зарегистрированного приложения.
`Instance`	Конечная точка службы токенов безопасности для проверки подлинности пользователей. Обычно это значение `https://login.microsoftonline.com/`, указывающее на общедоступное облако Azure.
`TenantId`	Имя клиента или идентификатор клиента (GUID) или `common` вход пользователей с помощью рабочих или учебных учетных записей или microsoft личная учетная запись.

Метод Configure() содержит два важных метода: app.UseAuthentication() и app.UseAuthorization(), которые обеспечивают упомянутые функциональные возможности.

// The runtime calls this method. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    // more code
    app.UseAuthentication();
    app.UseAuthorization();
    // more code
}

Защита контроллера, метода контроллера или страницы Razor

Методы контроллера или контроллера можно защитить с помощью атрибута [Authorize] . Этот атрибут разрешает доступ к контроллеру или методам только тем пользователям, которые прошли проверку подлинности. Если пользователь еще не прошел проверку подлинности, при обращении к контроллеру может быть отправлен запрос проверки подлинности.

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase

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

Код в API проверяет, указаны ли требуемые области в маркере, с помощью HttpContext.VerifyUserHasAnyAcceptedScope> (scopeRequiredByApi);:

namespace webapi.Controllers
{
    [Authorize]
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        // The web API will only accept tokens 1) for users, and 2) having the "access_as_user" scope for this API
        static readonly string[] scopeRequiredByApi = new string[] { "access_as_user" };

        [HttpGet]
        public IEnumerable<WeatherForecast> Get()
        {
            HttpContext.VerifyUserHasAnyAcceptedScope(scopeRequiredByApi);

            // some code here
        }
    }
}

Справка и поддержка

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

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

Следующий репозиторий GitHub содержит примеры кода веб-API ASP.NET Core и дополнительные примеры, демонстрирующие достижение следующих целей:

добавление проверки подлинности в новый веб-API ASP.NET Core;
вызов веб-API в классическом приложении;
вызов исходящих API, таких как Microsoft Graph и других API Майкрософт.

Учебники по веб-API ASP.NET Core на GitHub