ASP.NET Core · auth
14 глав · .NET 10
Содержание
Содержание
курс

Авторизация API
в ASP.NET Core

Кто ты, что тебе можно и как не оставить API открытым. JWT, политики, свои требования, cookie, API-ключи и отзыв токенов — с примерами, которые собираются и запускаются.

Курс про то, как в ASP.NET Core устроен вход в API: кто такой пользователь, откуда берётся его личность, как проверяется право на действие и как не наделать дыр по дороге. Всё на .NET 10, в стиле minimal API, с пометками там, где для контроллеров запись выглядит иначе.

Как читать. Четырнадцать глав, каждая — одна мысль и рабочий код. Почти все листинги собраны в два проекта и запущены на настоящем Kestrel: ответы, которые ты увидишь в примерах (401, 403, содержимое claims, поведение cookie и Identity) — это реальный вывод curl, а не пересказ документации. Примеры рассчитаны на net10.0; в .NET 8 и 9 всё то же самое, кроме мелочей, отмеченных отдельно.

1. Две разные вещи: аутентификация и авторизация

Аутентификация отвечает на вопрос «кто ты». Её результат — объект ClaimsPrincipal: набор утверждений (claims) о пользователе. Авторизация отвечает на вопрос «что тебе можно» и работает уже с этим объектом.

Разделение видно по кодам ответа:

  • 401 Unauthorized — «я не знаю, кто ты». Личность не установлена или токен невалиден. Ответ обязан содержать заголовок WWW-Authenticate.
  • 403 Forbidden — «я знаю, кто ты, но тебе сюда нельзя». Личность есть, прав нет.

Смешивать их — типичная ошибка: клиент по 401 идёт обновлять токен, а по 403 показывает «нет доступа». Если отдавать 401 на нехватку прав, клиент уйдёт в бесконечный цикл обновления токена.

Как это устроено внутри

запрос
  │
  ├─ UseAuthentication  → выбирает схему, строит ClaimsPrincipal (HttpContext.User)
  │
  ├─ UseAuthorization      → для эндпоинта берёт политику и прогоняет требования
  │
  └─ эндпоинт              → исполняется, только если политика разрешила

Три схемы, которыми пользуются в API:

Схема Кто её использует Где живёт состояние
JWT Bearer мобильные приложения, SPA, другие сервисы в самом токене (stateless)
Cookie браузер, server-side рендеринг, BFF в cookie + ключи Data Protection
Своя (API-ключ и т. п.) машинные интеграции, вебхуки где угодно: БД, конфиг, Redis

Главная развилка: JWT — для чужих клиентов, cookie — для своего браузерного фронта. Об этом подробно в главе 9.

Порядок middleware

var app = builder.Build();

app.UseAuthentication();   // сначала «кто ты»
app.UseAuthorization();    // потом «что можно»

app.MapGet("/me", ...).RequireAuthorization();
app.Run();

Перепутать порядок — самая частая причина «пользователь всегда анонимный»: UseAuthorization без UseAuthentication перед ним видит пустой User и режет всё в 401, хотя токен пришёл правильный. В minimal API приложение само неявно добавляет эти middleware при первом RequireAuthorization(), но если ты строишь pipeline руками (или используешь контроллеры), порядок обязателен.

2. Минимальный рабочий пример целиком

Задача: эндпоинт /login проверяет логин и пароль и выдаёт JWT; эндпоинт /me пускает только с этим токеном.

dotnet new web -o AuthDemo
cd AuthDemo
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Program.cs целиком — этот листинг компилируется и работает как есть:

using System.Security.Claims;
using System.Text;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);

// Ключ подписи. В продакшене — из конфигурации или хранилища секретов,
// длина не меньше 32 байт для HS256.
var signingKey = new SymmetricSecurityKey(
    Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]!));

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(o =>
    {
        o.MapInboundClaims = false;
        o.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = "authdemo",
            ValidateAudience = true,
            ValidAudience = "authdemo-api",
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            IssuerSigningKey = signingKey,
            ClockSkew = TimeSpan.FromSeconds(30),
            NameClaimType = "name",
            RoleClaimType = "role"
        };
    });

builder.Services.AddAuthorization();

var app = builder.Build();

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

app.MapPost("/login", (LoginRequest req) =>
{
    // Здесь была бы проверка по БД с хешем пароля (см. главу 12).
    if (req.User != "anton" || req.Password != "123")
        return Results.Unauthorized();

    var handler = new JsonWebTokenHandler();
    var token = handler.CreateToken(new SecurityTokenDescriptor
    {
        Issuer = "authdemo",
        Audience = "authdemo-api",
        Subject = new ClaimsIdentity(new[]
        {
            new Claim("sub", "42"),
            new Claim("name", "Антон"),
            new Claim("role", "user")
        }),
        Expires = DateTime.UtcNow.AddMinutes(15),
        SigningCredentials = new SigningCredentials(
            signingKey, SecurityAlgorithms.HmacSha256)
    });

    return Results.Ok(new { access_token = token, token_type = "Bearer" });
});

app.MapGet("/me", (ClaimsPrincipal user) => Results.Ok(new
{
    id = user.FindFirst("sub")?.Value,
    name = user.Identity?.Name
})).RequireAuthorization();

app.Run();

record LoginRequest(string User, string Password);

appsettings.json:

{
  "Jwt": {
    "Key": "dev-secret-key-at-least-32-bytes-long!!"
  }
}

Проверка в терминале — реальный вывод этой программы:

$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:5199/me
401

$ TOKEN=$(curl -s -X POST http://localhost:5199/login \
    -H 'Content-Type: application/json' \
    -d '{"user":"anton","password":"123"}' | jq -r .access_token)

$ curl -s http://localhost:5199/me -H "Authorization: Bearer $TOKEN"
{"id":"42","name":"Антон"}

$ curl -si http://localhost:5199/me | head -4
HTTP/1.1 401 Unauthorized
Content-Length: 0
WWW-Authenticate: Bearer

Три вещи в этом листинге неслучайны.

  1. Ключ — из конфигурации. Захардкоженный секрет в репозитории живёт там годами. Для локальной разработки — dotnet user-secrets set "Jwt:Key" "...", на сервере — переменная окружения или файл с правами 600.
  2. MapInboundClaims = false и явные NameClaimType/RoleClaimType — иначе User.FindFirst("sub") вернёт null, а роли перестанут работать. Почему — глава 4.
  3. Results.Unauthorized() на неверный пароль — это 401, а не 400: клиенту нужно понять, что дело в учётных данных, а не в теле запроса.

Важно. Для настоящего продакшена этого мало: пароль в открытом виде в примере — только чтобы не тащить в первую главу хеширование и БД. Логин по паролю без хеша (PBKDF2/BCrypt/Argon2) — это утечка всех паролей при первом же дампе базы.

3. Что внутри JWT и как его подписывать

JWT — три сегмента base64url через точку:

eyJhbGciOiJIUzI1NiJ9 . eyJzdWIiOiI0MiIsInJvbGUiOiJ1c2VyIn0 . 4f3h...9Q
└── header ────────┘ └──────── payload (claims) ────────┘ └ signature ┘
  • header — алгоритм подписи и тип токена.
  • payload — claims, обычный JSON. Раскодировать может кто угодно: base64 — это не шифрование. Никогда не клади в токен то, что нельзя показать клиенту.
  • signature — HMAC или RSA/ECDSA по header.payload.

Сервер не хранит токены: он проверяет подпись и срок. Отсюда главное следствие — отозвать выданный JWT нельзя (глава 11).

Выдача токена

Два API на выбор: старый JwtSecurityTokenHandler и новый JsonWebTokenHandler (он же используется внутри AddJwtBearer начиная с .NET 8). Бери новый.

using Microsoft.IdentityModel.JsonWebTokens;
using Microsoft.IdentityModel.Tokens;

var descriptor = new SecurityTokenDescriptor
{
    Issuer = "authdemo",
    Audience = "authdemo-api",
    Subject = new ClaimsIdentity(new[]
    {
        new Claim("sub", user.Id.ToString()),   // кто именно — стабильный ID
        new Claim("name", user.DisplayName),    // для логов и UI
        new Claim("role", user.Role),           // роль
        new Claim("scope", "orders:read orders:write")
    }),
    NotBefore = DateTime.UtcNow,
    Expires = DateTime.UtcNow.AddMinutes(15),
    SigningCredentials = new SigningCredentials(signingKey, SecurityAlgorithms.HmacSha256)
};

var token = new JsonWebTokenHandler().CreateToken(descriptor);

Полезные claims:

Claim Зачем Замечание
sub ID пользователя главный идентификатор, по нему ищем в БД
name отображаемое имя только для UI и логов
role роль работает с RequireRole (при RoleClaimType = "role")
scope права доступа для машин соглашение OAuth 2.0, удобно для API-to-API
jti ID токена нужен для чёрного списка при отзыве
iat, nbf, exp время выдачи / не раньше / истекает exp ставится из Expires

Токен — не место для списка прав на 200 записей: он ходит в каждом запросе и раздувает заголовок. Роли и грубые scope — можно; конкретные права на объекты — проверяй в базе (глава 7).

HS256 или RS256

HS256 — один общий секрет у того, кто подписывает, и того, кто проверяет. Годится, когда API и сервис выдачи — один процесс. Минус: любой проверяющий может подделать токен, потому что у него есть ключ подписи.

RS256 — приватный ключ только у сервиса авторизации, публичный у всех остальных. Нужен, когда API несколько или токены выдаёт отдельный сервис.

// Проверяющая сторона: ключ из PEM-файла
using var rsa = RSA.Create();
rsa.ImportFromPem(File.ReadAllText("public.pem"));

o.TokenValidationParameters.IssuerSigningKey = new RsaSecurityKey(rsa);
// ValidateIssuerSigningKey = true остаётся

Если токены выдаёт внешний провайдер (Keycloak, Entra ID, свой SSO), ключи не прописывают руками, а тянут из JWKS — они там ротируются:

.AddJwtBearer(o =>
{
    o.Authority = "https://login.example.com";   // читает /.well-known/openid-configuration
    o.Audience = "authdemo-api";
    // o.RequireHttpsMetadata = true — по умолчанию
})

При таком варианте IssuerSigningKey не задаётся: JwtBearer загрузит набор ключей сам и будет обновлять его при неизвестном kid.

4. Валидация токена: что именно проверяет JwtBearer

TokenValidationParameters — единственное место, где решается, доверять токену или нет. Каждый флаг выключает проверку; выключенная проверка — открытая дверь.

o.TokenValidationParameters = new TokenValidationParameters
{
    ValidateIssuer           = true,                    // iss совпадает
    ValidIssuer              = "authdemo",
    ValidateAudience         = true,                    // aud совпадает
    ValidAudience            = "authdemo-api",
    ValidateLifetime         = true,                    // exp/nbf в порядке
    ValidateIssuerSigningKey = true,                    // подпись верна
    IssuerSigningKey         = signingKey,
    ClockSkew                = TimeSpan.FromSeconds(30) // допуск на расхождение часов
};
  • ValidateAudience обязателен, если один и тот же ключ подписывает токены для разных API: без него токен, выданный для billing-api, пустят в admin-api. Классическая эскалация.
  • ClockSkew по умолчанию 5 минут: токен с exp минуту назад ещё примут. Для API с короткоживущими токенами ставь 30 секунд — тогда exp соблюдается почти точно.
  • ValidateLifetime = false не ставят никогда, даже «на время отладки»: такие флаги уезжают в прод.

Главный грабль: MapInboundClaims

По умолчанию JwtBearer переименовывает claims JWT в длинные схемы .NET (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier и т. п.). Это наследие WS-Federation, и оно ломает поиск по коротким именам. Вот реальный вывод одного и того же эндпоинта /me с токеном, в котором лежат sub, name, role:

По умолчанию (MapInboundClaims = true):

{"name":null,"nameIdentifier":"42","sub":null,
 "claims":[
   {"type":".../identity/claims/nameidentifier (бывший sub)","value":"42"},
   {"type":"name","value":"Антон"},
   {"type":".../identity/claims/role (бывший role)","value":"user"}]}

То есть User.FindFirst("sub") вернул null, а User.Identity.Name — тоже null, хотя claim name в токене есть. Роли при этом работают, потому что RequireRole ищет как раз длинный ClaimTypes.Role.

С рекомендуемой настройкой:

o.MapInboundClaims = false;
o.TokenValidationParameters.NameClaimType = "name";
o.TokenValidationParameters.RoleClaimType = "role";
{"name":"Антон","nameIdentifier":null,"sub":"42",
 "claims":[
   {"type":"sub","value":"42"},
   {"type":"name","value":"Антон"},
   {"type":"role","value":"user"}]}

Теперь claims называются так, как написано в токене, Identity.Name заполнен, RequireRole("admin") продолжает работать — но уже потому, что ты явно сказал, какой claim считать ролью. Забыть RoleClaimType при выключенном маппинге — вторая половина этого грабля: [Authorize(Roles = "admin")] начнёт отдавать 403 всем.

Правило. Один раз выбери MapInboundClaims = false + явные NameClaimType и RoleClaimType и держись этого во всех сервисах. Тогда claim в коде, в токене и в документации называются одинаково — sub, role, name.

5. Claims, роли и политики

Есть три уровня, и они складываются, а не заменяют друг друга.

1. Просто «вошёл» — самый частый случай для API:

app.MapGet("/me", ...).RequireAuthorization();

2. Роль — грубая проверка по claim role:

app.MapGet("/admin", ...).RequireAuthorization(p => p.RequireRole("admin"));

Несколько ролей в одном требовании — это «любая из»:

.RequireAuthorization(p => p.RequireRole("admin", "manager"))

3. Политика — именованный набор требований, который переиспользуется:

builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("Admin", p => p.RequireRole("admin"));

    o.AddPolicy("Adult", p => p
        .RequireAuthenticatedUser()
        .RequireClaim("age")                       // claim существует
        .RequireAssertion(ctx =>
            int.Parse(ctx.User.FindFirst("age")!.Value) >= 18));

    o.AddPolicy("VerifiedSeller", p => p
        .RequireAuthenticatedUser()
        .RequireClaim("seller_status", "verified", "trusted")  // любое из значений
        .RequireClaim("email_verified", "true"));
});

app.MapGet("/payouts", ...).RequireAuthorization("VerifiedSeller");

Что важно понимать про политики:

  • Требования внутри одной политики — это И (RequireClaim + RequireClaim = оба должны пройти).
  • Несколько атрибутов/вызовов RequireAuthorization на одном эндпоинте — тоже И.
  • RequireRole — это просто сахар над RequireClaim(ClaimTypes.Role, ...). Поэтому политика всегда гибче.
  • В контроллерах то же самое: [Authorize(Policy = "VerifiedSeller")], [Authorize(Roles = "admin,manager")], [AllowAnonymous] перекрывает всё остальное на этом action.

Защита по умолчанию

Политика по умолчанию применяется к эндпоинтам без собственных требований:

builder.Services.AddAuthorization(o =>
{
    o.FallbackPolicy = new AuthorizationPolicyBuilder()
        .RequireAuthenticatedUser()
        .Build();
});

Теперь забытый RequireAuthorization() на новом эндпоинте не открывает данные всему интернету: он по умолчанию закрыт. Открытые места помечают явно — .AllowAnonymous(). Для API это правильная настройка: ошибки «забыл закрыть» дороже, чем «забыл открыть».

6. Своё требование: IAuthorizationRequirement + handler

Политика на claims не умеет того, чего нет в токене. Пример: нужен возраст 18+, но в токене дата рождения, а не готовый флаг. Требование — это класс-маркер, handler — код, который решает, выполнено ли оно.

public sealed class MinimumAgeRequirement(int age) : IAuthorizationRequirement
{
    public int Age { get; } = age;
}

public sealed class MinimumAgeHandler : AuthorizationHandler<MinimumAgeRequirement>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context, MinimumAgeRequirement requirement)
    {
        if (!int.TryParse(context.User.FindFirst("age")?.Value, out var age))
            return Task.CompletedTask;              // не выполнено, но и не провал

        if (age >= requirement.Age)
            context.Succeed(requirement);           // выполнено

        return Task.CompletedTask;
    }
}

Регистрация — обычный DI, не забудь про неё (иначе политика молча всегда отказывает):

builder.Services.AddSingleton<IAuthorizationHandler, MinimumAgeHandler>();

builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("Adult", p => p
        .RequireAuthenticatedUser()
        .AddRequirements(new MinimumAgeRequirement(18)));
});

Проверено на живом приложении с токеном age=17:

$ AUTH="Authorization: Bearer $TOKEN"
$ curl -s -o /dev/null -w '%{http_code}\n' localhost:5199/adult -H "$AUTH"
403

Три неочевидные вещи:

  • Task.CompletedTask ≠ отказ навсегда. Handler просто ничего не сказал. Если хочешь запретить доступ независимо от других handler'ов — context.Fail(). Отсутствие Succeed при отсутствии Fail тоже даёт 403: требования проверяются как «все выполнены».
  • Handler'ов может быть несколько на одно требование, и они складываются по «или»: любой Succeed достаточно.
  • Handler с зависимостями. Если нужен DbContext или HTTP-клиент, регистрируй handler как Scoped и внедряй зависимости через конструктор: authorization выполняется в scope запроса, это нормально.

Когда хватает RequireClaim, пиши RequireClaim. Свой handler оправдан, когда решение требует кода: вычисления, похода в БД, сверки с внешним сервисом.

7. Авторизация по ресурсу: «этот документ — мой?»

Атрибуты и политики отвечают на вопрос «кто ты и какой у тебя класс доступа». Они не знают, к какому объекту идёт запрос. Для «может ли этот пользователь редактировать именно этот заказ» нужен второй шаг — проверка после загрузки объекта.

public sealed class DocumentOwnerRequirement : IAuthorizationRequirement;

public sealed class DocumentOwnerHandler
    : AuthorizationHandler<DocumentOwnerRequirement, Document>   // <требование, ресурс>
{
    protected override Task HandleRequirementAsync(
        AuthorizationHandlerContext context,
        DocumentOwnerRequirement requirement,
        Document resource)
    {
        if (context.User.FindFirst("sub")?.Value == resource.OwnerId)
            context.Succeed(requirement);

        return Task.CompletedTask;
    }
}

Политика регистрируется как обычно:

o.AddPolicy("DocumentOwner", p => p
    .RequireAuthenticatedUser()
    .AddRequirements(new DocumentOwnerRequirement()));

И применяется в коде, где объект уже есть:

app.MapGet("/documents/{id:int}", async (int id, ClaimsPrincipal user,
        IAuthorizationService authz, DocumentStore store) =>
{
    var doc = store.Get(id);
    if (doc is null) return Results.NotFound();          // 404 — объекта нет

    var result = await authz.AuthorizeAsync(user, doc, "DocumentOwner");
    if (!result.Succeeded) return Results.Forbid();      // 403 — объект есть, прав нет

    return Results.Ok(doc);
}).RequireAuthorization();

Живая проверка: пользователь sub=42 открывает свой документ и чужой.

$ AUTH="Authorization: Bearer $TOKEN"

$ curl -s -o /dev/null -w '%{http_code}\n' localhost:5199/documents/1 -H "$AUTH"
200
$ curl -s -o /dev/null -w '%{http_code}\n' localhost:5199/documents/2 -H "$AUTH"
403

Нюансы, на которых ломаются:

  • .RequireAuthorization() на эндпоинте всё равно нужен. Он отсекает анонимов до похода в базу; AuthorizeAsync — второй, точечный фильтр.
  • Сначала 404, потом 403. Если объект не найден — 404; если найден, но чужой — 403. Отвечать 404 на чужой объект (чтобы не раскрывать его существование) — законный выбор для чувствительных данных, но тогда не возвращай 403 вообще, иначе разница сама всё расскажет.
  • Не доверяй OwnerId из тела запроса. Владельца бери из sub, а не из JSON, иначе клиент «передаст» себе чужой документ.
  • AuthorizationHandler<TReq, TResource> не сработает без ресурса. Вызов AuthorizeAsync(user, "DocumentOwner") без объекта такой handler просто пропустит — политика откажет всем.

8. Minimal API: где именно ставится требование

В minimal API нет атрибутов на методах: авторизация — это вызов в конце цепочки Map*. [Authorize] на локальной функции или лямбде не делает ничего.

// Группа: требование наследуется всеми эндпоинтами внутри
var api = app.MapGroup("/api").RequireAuthorization();

api.MapGet("/orders", (ClaimsPrincipal user) => ...);         // закрыт

api.MapGet("/public/rates", () => ...).AllowAnonymous();      // открыт явно

// Политика по имени
app.MapGet("/payouts", ...).RequireAuthorization("VerifiedSeller");

// Требование прямо на месте, без регистрации политики
app.MapDelete("/users/{id:int}", ...)
   .RequireAuthorization(p => p.RequireRole("admin"));

Полезные детали:

  • Именованная политика читаемее и переиспользуется. RequireAuthorization(p => p.RequireRole("admin")) удобен для одного эндпоинта; как только правило встречается второй раз — выноси в AddPolicy.
  • RequireAuthorization() на конкретном эндпоинте не снимает требование группы. Требования складываются по «И». Чтобы открыть эндпоинт внутри закрытой группы, нужен .AllowAnonymous().
  • ClaimsPrincipal можно принять параметром — minimal API подставит HttpContext.User без [FromServices]. То же с IAuthorizationService.
  • Results.Forbid() возвращает 403, Results.Unauthorized() — 401, Results.Challenge() отдаёт вызов схеме (для JWT это тоже 401 с WWW-Authenticate). Внутри AuthorizeAsync-проверок используй Forbid: 401 там означает «токен протух», а это не тот случай.
  • Swagger UI не отправит токен, пока в документе OpenAPI нет схемы безопасности. В .NET 9+ это делается через IOpenApiDocumentTransformer: добавляешь securitySchemes с типом http/bearer и security на операции. Без этого кнопка Authorize в UI просто не появится, и половина ручных проверок будет выглядеть как «API не пускает».

Если фронтенд — свой сайт на том же домене, JWT часто лишний. Cookie даёт то, чего у JWT нет: браузер сам отправляет её, её нельзя прочитать из JS (при HttpOnly) и её можно мгновенно отозвать на сервере.

builder.Services
    .AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(o =>
    {
        o.Cookie.Name = "__Host-auth";        // префикс требует Secure + Path=/ + без Domain
        o.Cookie.HttpOnly = true;             // недоступна document.cookie
        o.Cookie.SecurePolicy = CookieSecurePolicy.Always;
        o.Cookie.SameSite = SameSiteMode.Lax; // Strict ломает переходы по ссылкам извне
        o.ExpireTimeSpan = TimeSpan.FromHours(8);
        o.SlidingExpiration = true;

        // Для API редирект на страницу логина бессмысленен
        o.Events.OnRedirectToLogin = ctx =>
        {
            ctx.Response.StatusCode = StatusCodes.Status401Unauthorized;
            return Task.CompletedTask;
        };
        o.Events.OnRedirectToAccessDenied = ctx =>
        {
            ctx.Response.StatusCode = StatusCodes.Status403Forbidden;
            return Task.CompletedTask;
        };
    });

Вход и выход:

app.MapPost("/session/login", async (HttpContext http, LoginRequest req, UserService users) =>
{
    var user = await users.CheckPasswordAsync(req.User, req.Password);
    if (user is null) return Results.Unauthorized();

    var identity = new ClaimsIdentity(
        new[]
        {
            new Claim("sub", user.Id.ToString()),
            new Claim("name", user.DisplayName),
            new Claim("role", user.Role)
        },
        CookieAuthenticationDefaults.AuthenticationScheme,
        nameType: "name",      // без этого User.Identity.Name == null
        roleType: "role");

    await http.SignInAsync(CookieAuthenticationDefaults.AuthenticationScheme,
        new ClaimsPrincipal(identity),
        new AuthenticationProperties { IsPersistent = true });

    return Results.NoContent();
});

app.MapPost("/session/logout", async (HttpContext http) =>
{
    await http.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
    return Results.NoContent();
});

Что обязательно помнить:

  • nameType/roleType в ClaimsIdentity. Claims в cookie не мапятся, и по умолчанию Identity.Name ищет длинный ClaimTypes.Name. Передай короткие имена в конструкторе — иначе User.Identity.Name будет null, хотя claim name в cookie лежит.
  • Без OnRedirectToLogin API будет отдавать 302 на /Account/Login. Мобильный клиент увидит редирект вместо 401 и решит, что «сервер сломался». Это отличает cookie-настройку для веб-страниц от cookie-настройки для API.
  • Cookie + POST = CSRF. Браузер приложит cookie к запросу с чужого сайта. Защита: SameSite=Lax/Strict (минимум), плюс antiforgery-токен для изменяющих запросов (builder.Services.AddAntiforgery(); app.UseAntiforgery();, для form-эндпоинтов проверка встроена).
  • __Host- префикс не даёт поддомену подменить cookie: только Secure, Path=/ и без Domain.
  • Масштабирование. Ключи Data Protection, которыми подписывается cookie, должны быть общими у всех инстансов (PersistKeysToFileSystem, ProtectKeysWith...), иначе инстанс A не примет cookie от инстанса B. Это ровно та ошибка, которая проявляется только после выката во второй контейнер.

Почему не JWT в localStorage

localStorage читается любым JS на странице, а значит любой XSS (включая скомпрометированную npm-зависимость) уносит токен целиком. Варианты по убыванию надёжности:

  1. BFF: браузер — только HttpOnly cookie, токены живут на сервере.
  2. JWT в памяти + refresh в HttpOnly cookie: access-токен не переживает перезагрузку, обновляется по refresh.
  3. JWT в localStorage — не надо.

10. API-ключи: своя схема аутентификации

Машинные интеграции (вебхуки, скрипты, чужие бэкенды) не умеют в интерактивный логин. Для них — своя схема: свой AuthenticationHandler, который читает ключ из заголовка и превращает его в ClaimsPrincipal.

using System.Security.Cryptography;
using System.Text;
using System.Text.Encodings.Web;
using Microsoft.AspNetCore.Authentication;
using Microsoft.Extensions.Options;

public sealed class ApiKeyHandler(
    IOptionsMonitor<AuthenticationSchemeOptions> options,
    ILoggerFactory logger,
    UrlEncoder encoder,
    IConfiguration config)
    : AuthenticationHandler<AuthenticationSchemeOptions>(options, logger, encoder)
{
    protected override Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!Request.Headers.TryGetValue("X-Api-Key", out var provided))
            return Task.FromResult(AuthenticateResult.NoResult()); // «не моя схема»

        var expected = config["ApiKeys:Gold"] ?? "";
        var same = CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(provided.ToString()),
            Encoding.UTF8.GetBytes(expected));

        if (!same)
            return Task.FromResult(AuthenticateResult.Fail("bad api key"));

        var identity = new ClaimsIdentity(
            [new Claim("sub", "service-1"), new Claim("badge", "gold")], "ApiKey");

        return Task.FromResult(AuthenticateResult.Success(
            new AuthenticationTicket(new ClaimsPrincipal(identity), "ApiKey")));
    }
}

Регистрация и политика, которая принимает только этот способ:

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(/* ... */)
    .AddScheme<AuthenticationSchemeOptions, ApiKeyHandler>("ApiKey", null, _ => { });

builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("Badge", p => p
        .AddAuthenticationSchemes("ApiKey")     // ключ, а не bearer
        .RequireAuthenticatedUser()
        .RequireClaim("badge", "gold"));
});

app.MapGet("/badge", ...).RequireAuthorization("Badge");

Проверено: ключ проходит, bearer-токен на этот же эндпоинт — нет.

$ curl -s -o /dev/null -w '%{http_code}\n' localhost:5199/badge \
    -H 'X-Api-Key: gold-key-1'
200
$ curl -s -o /dev/null -w '%{http_code}\n' localhost:5199/badge -H "$AUTH"
401

Обрати внимание: 401, а не 403. Схема в политике — часть проверки личности, и когда подходящей схемы нет, это «я не знаю, кто ты». Если бы эндпоинт пускал оба способа, ответ на чужой токен был бы 403.

Как принимать два способа сразу:

// атрибут в контроллере
[Authorize(AuthenticationSchemes = "ApiKey,Bearer")]

// или политика
o.AddPolicy("AnyClient", p => p
    .AddAuthenticationSchemes("ApiKey", JwtBearerDefaults.AuthenticationScheme)
    .RequireAuthenticatedUser());

Правила обращения с ключами:

  • Ключ — не пароль, его нельзя «помнить». Храни в базе только хеш (SHA-256 достаточно: ключ длинный и случайный), сверяй хеши, показывай ключ один раз при создании.
  • FixedTimeEquals, а не ==. Обычное сравнение строк завершается на первом несовпавшем байте и по времени ответа выдаёт префикс ключа.
  • Ключ на интеграцию, а не на человека. Отзыв = UPDATE api_keys SET revoked_at = now() WHERE id = ..., без «смены пароля у всех».
  • NoResult, а не Fail, если заголовка нет. Так схема не ломает другие способы аутентификации в том же pipeline.

11. Access + refresh: срок жизни и отзыв

Короткий access-токен — это компромисс: его нельзя отозвать, значит он должен быстро протухать. Чтобы пользователь не логинился каждые 15 минут, рядом живёт refresh-токен: долгий, хранимый на сервере, отзываемый.

/ login   → access (15 мин, в заголовок)  + refresh (30 дней, HttpOnly cookie, в БД хешем)
/ refresh → проверка refresh в БД → новый access + новый refresh (старый гасим)
/ logout  → refresh удаляем из БД; access доживает свои 15 минут

Эндпоинт обновления:

app.MapPost("/refresh", async (HttpContext http, RefreshStore store,
        TokenIssuer issuer) =>
{
    var raw = http.Request.Cookies["refresh"];
    if (string.IsNullOrEmpty(raw)) return Results.Unauthorized();

    var hash = SHA256.HashData(Encoding.UTF8.GetBytes(raw));

    // Атомарно: находим, проверяем срок, помечаем использованным.
    var session = await store.ConsumeAsync(hash);   // null, если нет/протух/уже использован
    if (session is null) return Results.Unauthorized();

    var (access, refresh) = await issuer.IssueAsync(session.UserId);

    http.Response.Cookies.Append("refresh", refresh, new CookieOptions
    {
        HttpOnly = true,
        Secure = true,
        SameSite = SameSiteMode.Lax,
        Expires = DateTimeOffset.UtcNow.AddDays(30),
        Path = "/refresh"          // cookie уходит только на этот путь
    });

    return Results.Ok(new { access_token = access });
}).AllowAnonymous();

Правила, которые отличают рабочую схему от декоративной:

  • Храни только хеш refresh-токена. Дамп базы не должен давать вход.
  • Ротация при каждом обновлении. Старый refresh гасится, выдаётся новый.
  • Повторное использование старого refresh — тревога. Это признак кражи: гаси всю сессию пользователя, а не просто отказывай.
  • Path = "/refresh" уменьшает поверхность утечки: cookie не уходит на каждый обычный запрос.
  • Отзыв access-токена — либо ждать exp, либо держать tv (token version) в claims и сверять с БД в OnTokenValidated (глава 13), либо чёрный список по jti. Первое дешевле всего, поэтому access и делают коротким.

12. ASP.NET Core Identity: готовые пользователи

Писать регистрацию, хеширование пароля, подтверждение email и 2FA руками — неделя работы и гора типовых дыр. Identity даёт это из коробки, а с .NET 8 — ещё и готовые эндпоинты.

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

public class AppDb(DbContextOptions<AppDb> options)
    : IdentityDbContext<IdentityUser>(options);

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDb>(o => o.UseSqlite("Data Source=app.db"));
builder.Services.AddAuthorization();
builder.Services.AddIdentityApiEndpoints<IdentityUser>()
    .AddEntityFrameworkStores<AppDb>();

var app = builder.Build();

app.MapIdentityApi<IdentityUser>();          // /register, /login, /refresh, /manage/*

app.MapGet("/me", (ClaimsPrincipal user) => user.Identity!.Name)
   .RequireAuthorization();

MapIdentityApi добавляет:

Маршрут Что делает
POST /register создаёт пользователя (email, password)
POST /login выдаёт bearer-токен; ?useCookies=true — вместо токена ставит cookie
POST /refresh обновляет токен
POST /confirmEmail, /resendConfirmationEmail подтверждение email
POST /forgotPassword, /resetPassword сброс пароля
GET/POST /manage/info, /manage/2fa профиль и двухфакторка

Что важно знать:

  • Роли по умолчанию не подключены. Нужен .AddRoles<IdentityRole>(), иначе RequireRole никогда не сработает — в токене просто нет claim role.
  • DTO фиксированные. /register принимает только email и пароль. Свои поля (имя, телефон) — либо через UserManager в своём эндпоинте, либо свой /login. Для API со своей моделью пользователя чаще пишут /login руками поверх UserManager.CheckPasswordAsync — Identity остаётся хранилищем и хешером.
  • AddIdentityApiEndpoints меняет схему аутентификации по умолчанию на свою (bearer + application cookie). Если в том же приложении живёт твой JWT, его токены перестают приниматься на эндпоинтах без явной схемы: запрос уходит в Identity, та отвечает 401 с сообщением «Unprotected token failed». Лечится указанием схемы в политике: .RequireAuthorization(p => p.AddAuthenticationSchemes(JwtBearerDefaults.AuthenticationScheme).RequireAuthenticatedUser()).
  • IUserClaimsPrincipalFactory<TUser> — точка, где в токен добавляются свои claims (например, role или tenant), если пользуешься готовым /login.
  • Пароль хешируется PBKDF2 с итерациями из настроек; не «улучшай» это сам.
  • MapIdentityApi занимает /login, /register и /refresh. Свой эндпоинт с таким же маршрутом не «переопределит» его, а получит AmbiguousMatchException при первом же запросе — 500, который выглядит как поломка Identity. Свои маршруты вешай на другой путь (/auth/login) или не подключай MapIdentityApi вовсе.
  • Смена схемы хранения (SQLite → Postgres) — это только UseNpgsql и миграции; сами таблицы Identity переносить не надо.

13. 401 против 403 на практике: ответы, события, логи

Что отдавать клиенту:

  • 401 — нет токена, протух, подпись не сошлась, схема не та. Обязателен WWW-Authenticate: Bearer.
  • 403 — личность установлена, прав нет. Тело — по желанию; полезно ProblemDetails с машинным кодом, чтобы клиент показал осмысленное сообщение.
  • 404 — объекта нет, или ты сознательно скрываешь его существование.

Стандартный ответ на запрос без токена — такой, и это реальный вывод Kestrel'а:

HTTP/1.1 401 Unauthorized
Content-Length: 0
WWW-Authenticate: Bearer

JwtBearerEvents — единственное место, где видно, почему токен не приняли. Без него в логах остаётся голый 401.

o.Events = new JwtBearerEvents
{
    OnAuthenticationFailed = ctx =>
    {
        // Причина: истёк, неверная подпись, неверный iss/aud...
        logger.LogWarning("JWT отклонён: {Reason}", ctx.Exception.Message);
        return Task.CompletedTask;
    },

    OnTokenValidated = async ctx =>
    {
        // Проверка состояния, которого нет в токене: бан, смена пароля, отзыв.
        var db = ctx.HttpContext.RequestServices.GetRequiredService<AppDb>();
        var sub = ctx.Principal!.FindFirst("sub")?.Value;
        var version = ctx.Principal.FindFirst("tv")?.Value;

        var user = await db.Users.FindAsync(long.Parse(sub!));
        if (user is null || user.TokenVersion.ToString() != version)
            ctx.Fail("токен отозван");
    },

    OnChallenge = async ctx =>
    {
        ctx.HandleResponse();                    // подавить стандартный ответ
        ctx.Response.StatusCode = StatusCodes.Status401Unauthorized;
        ctx.Response.ContentType = "application/problem+json";
        await ctx.Response.WriteAsJsonAsync(new
        {
            type = "https://httpstatuses.io/401",
            title = "unauthorized",
            status = 401,
            detail = "Токен отсутствует или недействителен"
        });
    }
};

Что логировать и что нет:

  • Логируй: sub, jti, iss, причину отказа, путь, IP.
  • Не логируй: сам токен, Authorization-заголовок, пароли, refresh-токены. Токен в логе — это утёкший токен, даже если срок короткий.
  • ctx.Fail() в OnTokenValidated отдаёт 401 — правильный код для «токен больше не действителен», а не 403.

14. Грабли и чек-лист

Десять ошибок, которые встречаются чаще всего. Почти все — конфигурация, а не код.

  1. UseAuthorization без UseAuthentication → все запросы анонимные, всё в 401. Порядок обязателен при ручном pipeline.
  2. MapInboundClaims оставлен по умолчанию → FindFirst("sub") = null, а в токене всё есть. Выключить маппинг и задать NameClaimType с RoleClaimType.
  3. ValidateAudience = false → токен чужого API открывает твой.
  4. ClockSkew не тронут → токен живёт на 5 минут дольше exp.
  5. Ключ HS256 короче 32 байт → IDX10720: Unable to create KeyedHashAlgorithm... key must be at least 256 bits. Проверяется в момент подписи/проверки, а не на старте.
  6. Секрет в appsettings.json, закоммиченном в git → user-secrets локально, переменные окружения на сервере.
  7. Cookie без OnRedirectToLogin → API отдаёт 302 вместо 401, мобильный клиент сходит с ума.
  8. Нет FallbackPolicy → новый эндпоинт без RequireAuthorization() открыт всем; политика по умолчанию переворачивает эту логику.
  9. Владелец объекта из тела запроса → клиент сам назначает себя владельцем. sub — единственный источник личности.
  10. 401 вместо 403 на нехватку прав → клиент уходит в цикл обновления токена, вместо того чтобы показать «нет доступа».

Чек-лист перед выкатом

  • HTTPS обязателен: UseHttpsRedirection(), UseHsts() в продакшене. По HTTP токен и cookie уходят открытым текстом.
  • Секреты не в репозитории; ключ подписи ≥ 32 байт, лежит в конфигурации или хранилище секретов.
  • ValidateIssuer, ValidateAudience, ValidateLifetime, ValidateIssuerSigningKey — все true.
  • MapInboundClaims = false, NameClaimType = "name", RoleClaimType = "role" — одинаково во всех сервисах.
  • FallbackPolicy закрывает всё, что не открыто явно, а открытое помечено .AllowAnonymous().
  • Access-токен живёт 5–15 минут, refresh хранится хешем и ротируется.
  • Cookie: HttpOnly, Secure, SameSite, __Host-, OnRedirectToLogin → 401.
  • CORS: конкретные origin'ы, AllowCredentials() только с ними (AllowAnyOrigin() + AllowCredentials() не работает по спецификации).
  • Проверки по объектам — через IAuthorizationService, с 404 для несуществующего и 403 для чужого.
  • В логах есть sub и причина отказа, но нет токенов и паролей.

Что дальше

  • OAuth 2.0 / OpenID Connect — если токены должны выдавать несколько сервисов или нужен вход через внешнего провайдера. В .NET это AddJwtBearer с Authority + отдельный сервер авторизации (Keycloak, Duende IdentityServer, Entra ID). Своего кода почти нет, конфигурации много.
  • Rate limiting по пользователю — AddRateLimiter с партиционированием по sub, чтобы один клиент не вычитывал API целиком.
  • Аудит — таблица «кто, что, когда» для изменяющих операций. Авторизация отвечает «можно», аудит отвечает «кто это сделал».
Материал проверен на .NET 10, листинги собраны и прогнаны через Kestrel: 401 без токена и с подправленной подписью, 200 с HS256- и RS256-токеном, 403 у чужого документа и у роли, которой нет, 401 у bearer-токена на эндпоинте с API-ключом, cookie-вход 204 и защищённый эндпоинт 200 по cookie, 401 без cookie, /refresh без refresh-cookie отдаёт 401, а MapIdentityApi регистрирует, логинит (200) и выдаёт и cookie, и bearer-токен.