Проверка подлинности и авторизация в минимальных API

Минимальные API поддерживают все параметры проверки подлинности и авторизации, доступные в ASP.NET Core, и предоставляют дополнительные функциональные возможности для улучшения возможностей управления проверкой подлинности.

В этой статье описывается поддержка проверки подлинности и авторизации в минимальных приложениях API, а также настройка и проверка функциональных возможностей.

Обзор концепций проверки подлинности и авторизации

Проверка подлинности — это процесс определения удостоверения пользователя во время авторизации— это процесс определения того, имеет ли пользователь доступ к ресурсу. Сценарии проверки подлинности и авторизации совместно используют аналогичную семантику реализации в ASP.NET Core.

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

Служба проверки подлинности

Служба проверки подлинности использует зарегистрированные обработчики для выполнения связанных с проверкой подлинности действий. Например, действие, связанное с аутентификацией, это аутентификация пользователя или выход из системы. Схемы проверки подлинности — это имена, которые используются для уникальной идентификации обработчика проверки подлинности и его параметров конфигурации. Обработчики проверки подлинности отвечают за реализацию стратегий проверки подлинности и создание утверждений пользователя с учетом определенной стратегии проверки подлинности, например OAuth или OIDC. Параметры конфигурации уникальны для стратегии и одновременно предоставляют обработчику настройки, влияющие на процесс аутентификации, такие как URI перенаправления.

Служба авторизации

На уровне авторизации существует две стратегии определения доступа пользователей к ресурсам:

• Стратегии на основе ролей определяют доступ пользователя на основе назначенной роли, например Administrator или User. Для получения дополнительной информации об авторизации на основе ролей см. документацию по авторизации на основе ролей.

• Стратегии на основе утверждений определяют доступ пользователя на основе утверждений, выданных центральным органом. Дополнительные сведения об авторизации на основе утверждений см. в документации по авторизации на основе утверждений.

В ASP.NET Core обе стратегии записываются в требование авторизации. Служба авторизации использует обработчики авторизации для определения того, соответствует ли конкретный пользователь требованиям авторизации для ресурса.

Включение проверки подлинности в минимальных приложениях

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

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Как правило, используется определенная стратегия проверки подлинности. В следующем примере приложение настроено с поддержкой проверки подлинности на основе веб-маркера JSON (JWT). В этом примере используются API,доступные в Microsoft. AspNetCore.Authentication.JwtBearer пакет NuGet.

var builder = WebApplication.CreateBuilder(args);
// Requires Microsoft.AspNetCore.Authentication.JwtBearer
builder.Services.AddAuthentication().AddJwtBearer();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

По умолчанию WebApplication автоматически регистрирует ПО промежуточного слоя проверки подлинности и авторизации, если включены определенные службы проверки подлинности и авторизации. В следующем примере не требуется вызывать методы UseAuthentication или UseAuthorization для регистрации ПО промежуточного слоя. WebApplication автоматически завершает регистрацию после вызова AddAuthentication метода или AddAuthorization метода.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

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

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors();
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseCors();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", () => "Hello World!");
app.Run();

Настройка стратегии проверки подлинности

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

• Проверка подлинности на основе носителя JWT
• Проверка подлинности на основе OpenID Connect

Платформа ASP.NET Core ожидает найти эти параметры в разделе Authentication:Schemes:{SchemeName} в разделе configuration. В следующем примере две разные схемы Bearer и LocalAuthIssuerопределяются соответствующими параметрами. Этот Authentication:DefaultScheme параметр можно использовать для настройки стратегии проверки подлинности по умолчанию.

{
  "Authentication": {
    "DefaultScheme":  "LocalAuthIssuer",
    "Schemes": {
      "Bearer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "dotnet-user-jwts"
      },
      "LocalAuthIssuer": {
        "ValidAudiences": [
          "https://localhost:7259",
          "http://localhost:5259"
        ],
        "ValidIssuer": "local-auth"
      }
    }
  }
}

В файле Program.cs две стратегии проверки подлинности на основе носителя JWT регистрируются со следующими именами схем:

• Несущий
• LocalAuthIssuer

Bearer — это типичная схема по умолчанию в приложениях на основе носителя JWT. Однако можно переопределить схему по умолчанию, задав DefaultScheme свойство, как показано в предыдущем примере.

Имя схемы используется для уникальной идентификации стратегии проверки подлинности. Имя также используется в качестве ключа поиска при определении параметров проверки подлинности из конфигурации, как показано в следующем примере:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication()
  .AddJwtBearer()
  .AddJwtBearer("LocalAuthIssuer");
  
var app = builder.Build();

app.MapGet("/", () => "Hello World!");
app.Run();

Настройка политик авторизации в минимальных приложениях

Проверка подлинности определяет и проверяет удостоверение пользователей в API. Авторизация подтверждает и верифицирует доступ к ресурсам в API. IAuthorizationService Служба, зарегистрированная методом AddAuthorization расширения, упрощает авторизацию. В следующем сценарии добавляется ресурс /hello, который требует от пользователя представить подтверждение роли admin с подтверждением области greetings_api.

Настройка требований авторизации к ресурсу — это двухэтапный процесс.

1. Определите требования авторизации в политике глобально.
2. Применение отдельных политик к ресурсам.

В следующем коде вызывается метод AddAuthorizationBuilder, который:

• Добавляет службы, связанные с авторизацией, в контейнер DI.
• Возвращает объект, который можно использовать для прямой регистрации политик авторизации.

Код создает новую политику авторизации с именем admin_greetings , которая инкапсулирует два требования авторизации:

• Требование на основе ролей для пользователей с ролью admin через RequireRole.
• Требование, основанное на утверждениях с помощью RequireClaim, для которого пользователь должен предоставить greetings_api утверждение области.

Политика admin_greetings предоставляется как обязательная политика для конечной точки /hello.

using Microsoft.Identity.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorizationBuilder()
  .AddPolicy("admin_greetings", policy =>
        policy
            .RequireRole("admin")
            .RequireClaim("scope", "greetings_api"));

var app = builder.Build();

app.MapGet("/hello", () => "Hello world!")
  .RequireAuthorization("admin_greetings");

app.Run();

Использование dotnet user-jwts для тестирования разработки

В примерах этой статьи используется приложение, настроенное с проверкой подлинности на основе носителя JWT. Проверка подлинности на основе носителя JWT требует от клиентов представить маркер в заголовке запроса, который используется для проверки их удостоверения и утверждений. Как правило, центральный орган, такой как сервер удостоверений, выдает токены.

Для разработки на локальном компьютере средство командной строки dotnet user-jwts можно использовать для создания маркеров носителя.

dotnet user-jwts create

Маркеры можно настроить с различными настройками. Например, чтобы создать токен для admin роли и greetings_api области, ожидаемых политикой авторизации в приведенном выше коде, запустите средство следующим образом:

dotnet user-jwts create --scope "greetings_api" --role "admin"

Затем созданный маркер можно отправить как часть заголовка в выбранном средстве тестирования. Например, чтобы отправить токен с помощью curl:

curl -i -H "Authorization: Bearer {token}" https://localhost:{port}/hello

Связанный контент

• Служба проверки подлинности (IAuthenticationService)
• Служба авторизации (IAuthorizationService)
• Промежуточное ПО ASP.NET Core
• Управление веб-токенами JSON с помощью средства dotnet user-jwts