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

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

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

Проверка подлинности — это процесс определения удостоверения пользователя. Авторизация — это процесс определения, есть ли у пользователя доступ к ресурсу. Сценарии проверки подлинности и авторизации совместно используют аналогичную семантику реализации в 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();

Как правило, используется определенная стратегия проверки подлинности. В следующем примере приложение настроено с поддержкой проверки подлинности на основе носителя 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} внутри конфигурации. В следующем примере две разные схемы 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.

• Название схемы «Bearer».
• Имя схемы "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 и упрощается методом расширения, зарегистрированным с помощью IAuthorizationServiceAddAuthorization. В следующем сценарии добавляется ресурс /hello, который требует от пользователя представить подтверждение роли admin с подтверждением области greetings_api.

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

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

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

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

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

• Требование на основе роли RequireRole для пользователей с ролью admin.
• Требование на основе утверждений через 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

Дополнительные сведения о средстве см. в полной dotnet user-jwtsдокументации.