Stage 9. JWT Basics
JWT (JSON Web Token) — это компактный формат передачи утверждений (claims) между сторонами, чаще всего между клиентом и API. JWT часто называют «удобным для микросервисов», но это верно только при правильной архитектуре валидации. Сам токен не делает систему безопасной автоматически. Безопасность появляется только при корректной выдаче, строгой проверке и управлении ключами.
1. Что такое JWT и зачем он нужен
JWT применяют, когда сервисам нужно проверять доступ stateless-способом: без чтения серверной session для каждого запроса. После логина клиент получает access token и отправляет его в заголовке Authorization.
Authorization: Bearer <access-token>
Преимущество: API может быстро проверить подпись и claims локально. Недостаток: сложнее мгновенно отозвать уже выданный токен, поэтому приходится строить отдельные механизмы revoke/short TTL.
2. Из каких частей состоит JWT
JWT состоит из трёх частей, разделённых точками:
header.payload.signature
header: алгоритм подписи и тип токена.payload: claims (sub,iss,aud,exp, scopes/roles и др.).signature: доказательство целостности и источника.
Важно: payload обычно не шифруется по умолчанию, он просто base64url-кодируется и легко декодируется. Поэтому чувствительные данные туда класть нельзя.
3. Полный JWT-поток в системе (один токен -> несколько сервисов)
Типичный поток в проде:
- Клиент проходит login на Auth Server.
- Auth Server выдает access JWT.
- Клиент вызывает API Gateway с bearer-токеном.
- Gateway делает первичную проверку.
- Запрос идёт в микросервисы, и каждый сервис повторно валидирует токен.
- Для проверки подписи сервисы используют публичные ключи (JWKS) и учитывают ротацию ключей.
Ключевой принцип: нельзя полагаться только на gateway. Каждый сервис, который принимает решение о доступе, обязан валидировать токен самостоятельно.
4. Какие проверки обязательны на каждом API
| Проверка | Зачем нужна |
|---|---|
| Подпись и allow-list алгоритмов | Защита от подмены токена и слабых/неожиданных alg |
iss (issuer) | Проверка, что токен выпущен доверенным auth-сервером |
aud (audience) | Токен должен быть предназначен именно этому API |
exp, nbf, iat | Контроль времени жизни и допустимого окна использования |
| Тип токена | Не путать access token и ID token |
| Scopes/Roles | Проверка предметных прав на действие |
Проверка только exp недостаточна. Именно неполная валидация чаще всего ломает безопасность в микросервисах.
5. JWT в микросервисах: теория эксплуатации
В распределённой системе важно единообразие. Если один сервис проверяет aud, а другой нет, пользователь увидит хаотичные 401/403 при одинаковом токене. Поэтому нужна общая библиотека/политика валидации и единый набор правил для всех команд.
Также критична ротация ключей: сервисы должны уметь безопасно принимать новый ключ и короткое время поддерживать старый (overlap window), иначе при ротации начнутся массовые отказы авторизации.
6. Частые ошибки новичков
- Класть в payload персональные или секретные данные.
- Проверять только подпись и
exp. - Принимать ID token как access token.
- Использовать длинный TTL access-токена «для удобства».
- Не логировать причины отказа валидации (
bad_signature,wrong_aud,token_expired).
Практический сценарий
В компании было три микросервиса и один gateway. Gateway проверял подпись и срок, но один из сервисов дополнительно требовал aud=payments, а другой aud вообще не проверял. В результате при одинаковом токене часть запросов проходила, а часть ломалась. После внедрения единой policy-библиотеки (общий набор проверок alg, iss, aud, time claims, token type, scopes), подключения JWKS с ротацией и унифицированного логирования причин отказа система стала предсказуемой. Этот кейс показывает: JWT работает хорошо не как «формат строки», а как дисциплина валидации во всей цепочке сервисов.