C# Academy · Урок

Структура JWT и утверждения

Разберитесь в заголовке, полезной нагрузке и подписи.

«Структура JWT и утверждения» — бесплатный урок C# Academy на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения C# Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс C# Academy содержит 4 уроков всего.

Что такое JWT

Веб-токен JSON (JWT) — это компактный безопасный для URL формат токена, используемый для безопасной передачи утверждений между двумя сторонами. В ASP.NET Core это наиболее распространённый способ аутентификации API без сохранения состояния.

JWT — это всего лишь строка из трёх частей, закодированных в Base64Url и соединённых точками: header.payload.signature.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0Iiwicm9sZSI6ImFkbWluIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Заголовок

Заголовок описывает способ подписи токена. Это небольшой объект JSON, который кодируется в Base64Url и становится первым сегментом.

alg указывает алгоритм подписи (например, HS256 или RS256), а typ почти всегда имеет значение JWT.

{
  "alg": "HS256",
  "typ": "JWT"
}

Полезная нагрузка

Полезная нагрузка содержит утверждения — сведения о пользователе и метаданные токена. Это второй сегмент.

Важно: полезная нагрузка только закодирована, но не зашифрована. Любой может расшифровать её содержимое, поэтому никогда не помещайте сюда секреты.

{
  "sub": "1234",
  "name": "Alice",
  "role": "admin",
  "exp": 1735689600
}

Подпись

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

Если кто-либо изменит хотя бы один символ полезной нагрузки, подпись больше не совпадёт и проверка завершится неудачно.

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secretKey
)

Зарегистрированные утверждения

Некоторые имена утверждений стандартизированы спецификацией JWT (RFC 7519). Для них используются короткие ключи из трёх букв:

iss — издатель
sub — субъект (идентификатор пользователя)
aud — аудитория
exp — время истечения срока действия (секунды Unix)
nbf — недействительно до
iat — время выпуска

{
  "iss": "https://api.myapp.com",
  "aud": "myapp-clients",
  "sub": "42",
  "exp": 1735689600,
  "iat": 1735686000
}

Пользовательские утверждения

Помимо зарегистрированного набора Вы можете добавлять любые пользовательские утверждения, необходимые приложению: роли, разрешения, идентификаторы арендаторов, адрес электронной почты и другие данные.

Не увеличивайте размер полезной нагрузки: каждое утверждение передаётся с каждым запросом.

{
  "sub": "42",
  "email": "alice@myapp.com",
  "role": "admin",
  "tenant_id": "acme",
  "permissions": ["orders:read", "orders:write"]
}

Утверждения в ASP.NET Core

В .NET утверждения представлены типом System.Security.Claims.Claim. Каждое утверждение представляет собой пару тип / значение.

При проверке JWT ASP.NET Core превращает каждую запись полезной нагрузки в объект Claim в составе ClaimsPrincipal пользователя.

var claims = new List<Claim>
{
    new Claim(ClaimTypes.NameIdentifier, "42"),
    new Claim(ClaimTypes.Name, "Alice"),
    new Claim(ClaimTypes.Role, "admin"),
    new Claim("tenant_id", "acme")
};

ClaimsPrincipal и ClaimsIdentity

Аутентифицированный пользователь представлен объектом ClaimsPrincipal, который содержит один или несколько объектов ClaimsIdentity, каждый из которых хранит набор утверждений.

В контроллере доступ к нему осуществляется через User.

// Inside a controller action
var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
bool isAdmin = User.IsInRole("admin");
string? tenant = User.FindFirst("tenant_id")?.Value;

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

По умолчанию обработчик JWT сопоставляет короткие ключи JWT с длинными типами утверждений в формате URI (например, sub преобразуется в ClaimTypes.NameIdentifier).

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

JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
// Now User.FindFirst("sub") returns the raw 'sub' claim

Почему бы не использовать просто cookie сеанса

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

Это делает их идеальными для горизонтально масштабируемых API и микросервисов, где любой узел может проверить один и тот же токен.

// Client sends the token on every request:
// Authorization: Bearer eyJhbGciOiJIUzI1Ni...

Компромисс: отзыв токенов

Поскольку JWT является самодостаточным и считается доверенным до истечения срока действия, его нельзя легко отозвать до времени, указанного в exp.

Обычно эту проблему решают, используя токены доступа с коротким сроком действия в сочетании с токенами обновления (об этом рассказывается далее в курсе).

// Short-lived access token
exp = iat + 15 * 60;  // 15 minutes

Быстрая проверка

Проверьте своё понимание структуры JWT.

Повторение

Вы изучили строение JWT и принцип работы утверждений в ASP.NET Core:

JWT состоит из header.payload.signature, каждая часть закодирована в формате Base64Url.
Полезная нагрузка содержит зарегистрированные и пользовательские утверждения, закодированные, но не зашифрованные.
Подпись гарантирует целостность с помощью секрета или пары ключей.
.NET преобразует утверждения в объект ClaimsPrincipal, который читается через User.

Далее вы настроите ASP.NET Core для проверки этих токенов.

Часто задаваемые вопросы

Урок «Структура JWT и утверждения» бесплатный?

Да — полный текст урока «Структура JWT и утверждения» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс C# Academy, подпишись на CoddyKit PRO. Курс C# Academy содержит 4 уроков всего.

Чему я научусь в уроке «Структура JWT и утверждения»?

Разберитесь в заголовке, полезной нагрузке и подписи. Ты практикуешь C# Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать C# Academy?

Предыдущий опыт не требуется. C# Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Структура JWT и утверждения»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке C# Academy?

Да. Каждый урок C# Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к C# Academy