golang-jwt v5: первый токен

В golang-jwt v5 выпуск токена распадается на две операции, и обе умещаются в одну строку каждая. jwt.NewWithClaims(method, claims) собирает заготовку: в неё уходят алгоритм подписи — для нашего курса jwt.SigningMethodHS256 — и набор claims, например jwt.MapClaims. Результат — указатель на jwt.Token, ещё не строка: токен не подписан. Вторая операция — SignedString(key): метод пересчитывает подпись тем алгоритмом, который был заявлен в NewWithClaims, и склеивает три части в финальную строку. Ключ для HS256 — срез байтов секрета, []byte(secret). Разделение не бюрократия: между сборкой и подписью можно заглянуть внутрь заготовки в отладчике, а сам интерфейс один и тот же для HS256, RS256 и ES256 — поменяются только алгоритм и тип ключа. Ошибка, если секрет окажется не того типа, вернётся второй возвращаемой величиной — привычная идиома Go, без паник и молчаливых провалов.

Запустите программу — и на экране появится строка, которую вы уже умеете читать после урока про устройство токена: два куска base64url, точка, ещё кусок. Первый декодируется в заголовок с alg HS256, второй — в ваши claims с sub и role, третий — подпись, непрозрачная строка байтов. Полезная привычка: прогнать только что выпущенный токен через jwt.io или любой оффлайн-декодер и убедиться, что содержимое совпадает с задуманным — так ловятся опечатки в именах полей до того, как они доедут до клиента. Заодно проверка наглядно показывает цену безопасности: декодер без вашего секрета пометит подпись невалидной и будет прав — он же не знает ключа. Сам токен на вид стандартен, и именно поэтому к нему легко привыкнуть как к чёрному ящику; знание анатомии из прошлого урока — то, что оставит ящик открытым.

Два ингредиента программы заслуживают отдельного слова. Секрет — строка из окружения, и её качество мы разберём в уроке про HMAC: пока важно лишь то, что она не хардкодится и не коммитится. Claims — это jwt.MapClaims, то есть map[string]any: имена полей произвольные, значения любые. Стандарту RFC 7519 соответствуют sub и exp; role — поле нашего проекта, и его права на жизнь обсуждаются в уроке про claims. Обратите внимание на exp: без него токен выпустится без единого предупреждения и будет валиден вечно — библиотека не заставляет срок годности при выпуске, это ваша ответственность как выпускающего. Пятнадцать минут — привычный срок для access-токена в паре с refresh-схемой, до которой курс доберётся в середине. А если хочется строгой гарантии на стороне проверки — она появится в виде опции WithExpirationRequired там же, в уроке про claims.

У самой простой программы урока есть тёмная сторона, и она стоит реальных инцидентов. Забыли ExpiresAt при выпуске, парсер на проверке остался без WithExpirationRequired — и токен, которого нет ни в базе, ни в сессиях, нельзя отозвать кнопкой, будет приниматься годами. Хуже того, такой токен часто выпускается в отладке с ролью admin и расползается по логам, скриншотам и тестовым записям. Утечка обычного токена лечится ожиданием: пятнадцать минут — и мёртв. Утечка вечного лечится только ротацией секрета, то есть перелогином всех пользователей сразу. Диагностика простая: декодируйте payload подозрительного токена — если exp в нём нет, перед вами не баг проверки, а дыра выпуска. Страховка умещается в две строки: exp при каждом выпуске и WithExpirationRequired при каждой проверке; обе разбираем в следующем уроке про claims.

Токен без проверки — половина дела, и библиотека позволяет проверить выпущенное в той же программе. jwt.ParseWithClaims принимает строку, контейнер для claims и keyfunc — функцию, которая возвращает ключ проверки. Для HS256 это тот же []byte(secret). Опция jwt.WithValidMethods([]string{"HS256"}) фиксирует ожидаемый алгоритм и отбрасывает токены с чужим alg до всякой проверки подписи — привычка, которую стоит ставить с первого дня. Если ошибок нет и parsed.Valid равен true, токен подписан нами и не просрочен, а claims уже декодированы в переданный контейнер. Полный разбор парсинга, keyfunc и всех типов ошибок — тема шестого урока, здесь важен сам факт: выпуск и проверка живут в одной библиотеке и делят один секрет.

Урок был бы неполным без спорного мнения: JWT — не автоматическое улучшение классических серверных сессий. Сессия в Redis отзывается мгновенно: сервер удалил ключ — и всё. Токен живёт у клиента до exp, и мгновенный выход требует denylist по jti, то есть хранилища и похода в него при каждой проверке — ровно того stateless, ради которого JWT обычно брали. Если у вас монолит с серверными страницами и один процесс, cookie-сессия проще и честнее. JWT выигрывает там, где проверять токены должны несколько независимых сервисов без общего хранилища: шлюз сверяет подпись на входе, бэкенд и фоновые воркеры делают то же, и никто не ходит в базу сессий. Я выбираю JWT осознанно, под задачу распределённой проверки, а не по умолчанию — правильный вопрос на ревью не «JWT или сессии», а «кто и где проверяет». Цене отзыва посвящён урок про denylist.