Курс про то, как в ASP.NET Core устроен вход в API: кто такой пользователь, откуда берётся его личность, как проверяется право на действие и как не наделать дыр по дороге. Всё на .NET 10, в стиле minimal API, с пометками там, где для контроллеров запись выглядит иначе.
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
Три вещи в этом листинге неслучайны.
- Ключ — из конфигурации. Захардкоженный секрет в репозитории живёт там
годами. Для локальной разработки —
dotnet user-secrets set "Jwt:Key" "...", на сервере — переменная окружения или файл с правами600. MapInboundClaims = falseи явныеNameClaimType/RoleClaimType— иначеUser.FindFirst("sub")вернётnull, а роли перестанут работать. Почему — глава 4.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 не пускает».
9. Cookie-аутентификация: когда JWT не нужен
Если фронтенд — свой сайт на том же домене, 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, хотя claimnameв cookie лежит.- Без
OnRedirectToLoginAPI будет отдавать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-зависимость) уносит токен целиком. Варианты по убыванию
надёжности:
- BFF: браузер — только
HttpOnlycookie, токены живут на сервере. - JWT в памяти + refresh в
HttpOnlycookie: access-токен не переживает перезагрузку, обновляется по refresh. - 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никогда не сработает — в токене просто нет claimrole. - 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. Грабли и чек-лист
Десять ошибок, которые встречаются чаще всего. Почти все — конфигурация, а не код.
UseAuthorizationбезUseAuthentication→ все запросы анонимные, всё в401. Порядок обязателен при ручном pipeline.MapInboundClaimsоставлен по умолчанию →FindFirst("sub")=null, а в токене всё есть. Выключить маппинг и задатьNameClaimTypeсRoleClaimType.ValidateAudience = false→ токен чужого API открывает твой.ClockSkewне тронут → токен живёт на 5 минут дольшеexp.- Ключ HS256 короче 32 байт →
IDX10720: Unable to create KeyedHashAlgorithm... key must be at least 256 bits. Проверяется в момент подписи/проверки, а не на старте. - Секрет в
appsettings.json, закоммиченном в git → user-secrets локально, переменные окружения на сервере. - Cookie без
OnRedirectToLogin→ API отдаёт302вместо401, мобильный клиент сходит с ума. - Нет
FallbackPolicy→ новый эндпоинт безRequireAuthorization()открыт всем; политика по умолчанию переворачивает эту логику. - Владелец объекта из тела запроса → клиент сам назначает себя владельцем.
sub— единственный источник личности. 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 целиком. - Аудит — таблица «кто, что, когда» для изменяющих операций. Авторизация отвечает «можно», аудит отвечает «кто это сделал».
401 без токена и с подправленной подписью, 200 с
HS256- и RS256-токеном, 403 у чужого документа и у роли, которой
нет, 401 у bearer-токена на эндпоинте с API-ключом, cookie-вход
204 и защищённый эндпоинт 200 по cookie,
401 без cookie, /refresh без refresh-cookie отдаёт
401, а MapIdentityApi регистрирует, логинит
(200) и выдаёт и cookie, и bearer-токен.