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

Примечание.

Это не последняя версия этой статьи. В текущем выпуске см . версию .NET 9 этой статьи.

Предупреждение

Эта версия ASP.NET Core больше не поддерживается. Дополнительные сведения см. в политике поддержки .NET и .NET Core. В текущем выпуске см . версию .NET 9 этой статьи.

Внимание

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

В текущем выпуске см . версию .NET 9 этой статьи.

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

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

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

Платформа 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 регистрируются следующие:

• Имя схемы носителя.
• Имя схемы 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();

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

Проверка подлинности используется для идентификации и проверки identity пользователей в API. Авторизация используется для проверки и проверки доступа к ресурсам в API и облегчается IAuthorizationService AddAuthorization зарегистрированным методом расширения. В следующем сценарии добавляется ресурс, /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 требует, чтобы клиенты отображали маркер в заголовке запроса для проверки их identity и утверждений. Как правило, эти маркеры выдаются центральным центром, например сервером identity .

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

dotnet user-jwts create

Примечание.

При вызове в проекте средство автоматически добавляет параметры проверки подлинности, соответствующие созданному маркеру appsettings.json.

Маркеры можно настроить с различными настройками. Например, чтобы создать маркер для 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 документации.