Аутентификация JWT

Сессия из прошлого урока — разговор через камеру хранения: пользователь получает билетик, всё содержимое сумки лежит на сервере. Надёжно, но у схемы есть цена: сервер обязан помнить каждую сессию, кластер обязан помнить их одинаково, а клиентам без cookie — мобильным приложениям, другим бэкендам, CLI — приходится имитировать cookie jar. gin jwt — вторая большая схема аутентификации, stateless: всё содержимое «сумки» подписывается и отдаётся клиенту целиком в токене. Сервер хранит только секрет подписи — одна строка байтов, одинаковая для всех реплик; каждый узел кластера проверяет токен самостоятельно, redis не нужен, рестарт ничего не стирает. Токен — это три строки base64url, склеенные точками: header.payload.signature. Header описывает алгоритм подписи, payload — данные (claims): кто пользователь, какая роль, до какого времени годен, когда выдан. Signature — подпись первых двух строк ключом сервера: изменить payload, не пересчитав подпись, нельзя, а пересчитать её без ключа — нельзя в принципе. Заметим сразу, что нужно, чтобы не обмануться: подпись — это не шифрование. Токен кодируется, а не зашифрован — любой, кто его увидел, прочитает содержимое; секрет не даёт ИЗМЕНИТЬ, но не даёт СКРЫТЬ. Отсюда всё богатство уроков ниже: что можно класть в claims, что нельзя, и почему логаут с stateless-токеном — отдельная инженерная задача. Фраза «jwt авторизация go» в поиске обычно означает ровно три операции — выдать, проверить, обновить — и все три разберём на нашем трекере: /api/v1/todos станет доступен только с валидным токеном.

Заголовок — маленький JSON вроде {"alg":"HS256","typ":"JWT"}: alg — алгоритм подписи, typ — тип. Полезная нагрузка — JSON с claims, и часть имён тут стандартизирована RFC 7519: iss (issuer) — кто выдал токен, sub (subject) — о ком он, aud (audience) — для какого потребителя, exp (expiration) — время смерти в секундах unix, iat (issued at) — когда выдан, nbf (not before) — не принимай раньше, jti (JWT ID) — уникальный идентификатор токена, через который потом ищут и отзывают конкретные токены. Поверх стандартных кладут свои: user_id, role, версия прав доступа. Всё это — слова, которые сервер сам написал и сам подписал: вот почему middleware готов верить им без похода в базу. Третья часть — подпись: HMAC-SHA256(header.payload, secret) для HS256 или RSA-ECDSA-подпись для RS256/ES256. Проверка сервера элементарна: пересчитать подпись первых двух частей своим ключом и сравнить. Разберём три следствия, на которых ловят новички. Первое: base64url — это кодирование, декодер строится в три строки, сайт jwt.io показывает payload наглядно — не кладите в токен ничего, что не готовы показать. Второе: «alg»: «none» — историческая атака: некоторые старые библиотеки принимали токены без подписи, если в header написано none; современная golang-jwt отклоняет такое, но проверять ожидаемый алгоритм всё равно нужно явно — увидим в keyfunc. Третье: confusion HS256/RS256 — если сервер подписывает RS256 приватным ключом, а в keyfunc наивно возвращает тот же байтовый секрет, атакующий переклеит alg на HS256 и подпишет токен публичным ключом, который и так известен; вывод — проверять t.Method жестко, а не доверять header. exp, iat и nbf библиотека проверяет сама, если claims реализуют нужные методы, — об этом дальше.

Прежде чем выдавать токен, надо проверить, кому выдаёшь, — и JWT тут ни при чём: пароли — отдельная дисциплина. Хендлер POST /api/v1/login принимает LoginInput со структурой из урока про binding и валидацию: Username с тегом binding:"required,min=3" и Password с binding:"required,min=8" — validator отсечёт пустышки ещё до похода в хранилище пользователей. Пароль в базе хранится хэшем, а не текстом: при регистрации пользователь проходит bcrypt.GenerateFromPassword, при логине — bcrypt.CompareHashAndPassword, и совпадение говорит «это он» без того, чтобы сервер хоть раз видел plaintext. Никогда не кладите пароль или его хэш в claims: payload читается всеми, кто увидел токен, и живет в нем до exp. Ошибка аутентификации отвечайте единым «логин или пароль неверны» со статусом 401: не уточняйте, что именно неверное, — не дарите переборщику подсказок. Тот же принцип тишины — в логах: логируйте факт выдачи с jti и user_id, но не сам токен и не пароль; токен, попавший в лог, становится легитимным ключом до exp. И держите в голове нагрузку: /login — единственный эндпоинт, где plaintext пароля существует, поэтому он же — любимая цель перебора; ограничение частоты запросов на него поставит middleware из урока про rate limiting, а здесь запомним: выдача токена — это проверка пароля, сборка claims и подпись, всё остальное — декорации.

Обратная операция — jwt.ParseWithClaims(tokenStr, &UserClaims{}, keyfunc): библиотека режет строку по точкам, декодирует header и payload, зовёт ваш keyfunc за ключом проверки и сверяет подпись, а заодно валидирует exp, iat и nbf, если они заполнены. Вся логика доверия живёт в keyfunc — и это место, где ставят два замка. Первый — алгоритм: func(t jwt.Token) (any, error) { if _, ok := t.Method.(jwt.SigningMethodHMAC); !ok { return nil, fmt.Errorf("неожиданный alg: %v", t.Header["alg"]) }; return secret, nil } — токен с другим alg отвергается до сверки подписи, и «alg»: «none» с HS256/RS256-confusion отсекаются одним if-ом. Второй — сам ключ: для HS256 это []byte того же JWT_SECRET, что подписывал. Возврат — пара (*jwt.Token, error), и работа с ошибкой здесь дисциплинирует: ошибки v5 агрегированы и различаются через errors.Is — jwt.ErrTokenExpired для протухшего exp, jwt.ErrTokenNotValidYet для nbf, jwt.ErrTokenSignatureInvalid для подделки, jwt.ErrTokenMalformed для строки без двух точек. Ответ клиенту по этим ошибкам одинаковый — 401, но текст разный: на Expired вежливо подсказывают refresh, на Signature ничего не объясняют. Проверять token.Valid необязательно: если err == nil, токен жив и подписан; claims уже заполнились в вашей структуре — UserClaims, в которую ParseWithClaims декодировал payload, готова к чтению. Для внутреннего кода удобно вынести keyfunc в переменную verifyKey и переиспользовать в гварде и в refresh-эндпоинте — один источник истины про алгоритм и ключ, ноль расхождений.

Жизненный цикл access-токена — компромисс между безопасностью и удобством. Живёт 15 минут: украденный токен умрёт быстро, но и пользователь будет пере-логиниваться каждые четверть часа — непростимо. Живёт неделю: удобно, но кража открывает неделю доступа, а отозвать stateless-токен нельзя. Стандартное решение — пара токенов: короткий access на 5-15 минут для каждого запроса к API и долгий refresh на дни-недели, который живёт в одной цели — получить новый access. POST /api/v1/token/refresh принимает refresh, проверяет той же verifyKey (отдельный claims-тип с типом в payload поможет не спутать пару), убеждается, что это refresh, а не access, и выдаёт свежий access; пароль заново не спрашивается. Храните refresh серьёзнее access: HttpOnly cookie из урока про cookie вместо localStorage или серверная запись. Ротация refresh — каждый refresh-запрос выдает и новый refresh, а старый инвалидирует; для этого нужен jti и хранилище (redis из прошлого урока) — и вы снова stateful, но только в одном месте. Logout с JWT — признание слабости stateless: токен подписан и жив до exp, сервер «забыть» его не может. Рабочие ответы: короткий exp как главный лимит вреда; denylist по jti — проверяете в гварде, не в списке ли отозванных, снова нужно хранилище; поле token_version в claims, инкрементируемое при смене пароля, — инвалидирует все токены пользователя разом. Для нашего трекера достаточно exp в 15 минут и refresh на сутки: утечка жёстко ограничена по времени, а инфраструктура отзыва не нужна.

Секрет HS256 — единственная строка, от которой зависит вся схема, и обращение с ней показывает зрелость проекта. Источник — переменная окружения: os.Getenv("JWT_SECRET") при старте, и если пусто, падайте на запуске с внятной ошибкой: приложение, которое тихо подписывает токены пустым ключом, — дыра в готовом виде. Размер — не меньше 32 случайных байта, сгенерированные openssl rand -base64 32, а не «пароль компании»; в git — только .env.example. Ротация: добавить в header токенов поле kid (key ID) и держать несколько ключей — подписываете новым, проверяете по kid, старый выбрасываете, когда все exp истекли. Теперь алгоритмы. HS256 — симметричный: тот же секрет подписывает и проверяет, поэтому проверяющая сторона может и выдавать токены; для одного сервиса — идеально. RS256 и ES256 — асимметричные: auth-сервис подписывает приватным ключом, API проверяют публичным, который можно хоть на странице опубликовать. Проверяющий физически не может подделать токен — и это снимает целый класс вопросов, когда токен выпускает один сервис, а потребляют пять: identity-провайдер подписывает, все микросервисы проверяют публичным ключом, публикуемым через JWKS-эндпоинт. Для трекера на одном бинарнике HS256 достаточно, и усложнять не нужно; но когда появится второй сервис — переезд на RS256 заменит одну строку в keyfunc и одну в issueToken. Отдельный урок — хранение токена на клиенте, но и оно вытекает из анатомии: localStorage читает любой XSS (уроки про шаблоны и cookie это уже разбирали), HttpOnly cookie не читает никто, но её приложит CSRF-сценарий; рабочая схема для SPA — access в памяти JS, refresh в HttpOnly cookie, и эту связку доверши разбор CSRF в следующем уроке.

Схемы не соперники, а инструменты, и выбор диктуют клиенты и требования. Хранение: сессия — на сервере, JWT — у клиента; значит, отзыв сессии — DEL в redis, отзыв JWT — только exp, denylist или token_version. Размер: id сессии — строка в 30-60 байт каждый запрос, JWT с claims — полкилобайта и больше на каждый вызов API — при тысячах запросов в секунду это заметные байты. Масштабирование: обе схемы горизонтальны, но сессии требуют общего хранилища, JWT — только общего секрета. Отладка: сессию видно в redis и в DevTools, JWT — только DevTools, и токен невозможно «поправить руками» — только перевыпустить. Клиенты: браузер любит cookie и сессии, мобильные приложения и бэкенд-потребители — Authorization-заголовок; cookie-транспорт для API-клиентов лишний, а JWT в localStorage для браузера — уязвимость. Практический вывод для трекера: держать обе схемы. Веб-интерфейс из урока про шаблоны живёт на сессиях из прошлого урока: SSR-страницы, cookie с HttpOnly, мгновенный logout через Clear. API /api/v1 — на JWT: мобильный клиент и будущие интеграции шлют Bearer без cookie, сервер не хранит ничего, auth-сервис можно вынести отдельно. Гибрид с одной точкой входа: /login может выдавать и то, и другое — сессию для браузера и пару токенов для API; гвард Auth() защищает только группу /api/v1, сессионное звено — только HTML-маршруты, и схемы не смешиваются в одном запросе. Когда появится микросервисная архитектура, JWT станет мостом между сервисами — и переезд на RS256 с JWKS будет напрашиваться сам.

Поломанный JWT-флоу диагностируется по ответу 401, а его причины — по тексту ошибки, который гвард честно не показывает клиенту, но показывает вам в логе. Ошибка jwt.ErrTokenMalformed — строка не режется на три части: клиент прислал не токен, а JSON-ответ целиком (не выделил поле из {"access_token": "..."}), забыл префикс Bearer или прислал пустой заголовок; смотрите, что реально лежит в Authorization. ErrTokenSignatureInvalid — подпись не сошлась: сервер подписывает одним секретом, проверяет другим (два окружения, два .env), или токен склеили из частей двух разных токенов руками; сверяйте JWT_SECRET в обоих концах. ErrTokenExpired — exp прошёл: самый честный случай, refresh-эндпоинт для него и написан; если exp «не наступает», проверьте, что jwt.NewNumericDate берёт time.Now(), а не нулевое время. ErrTokenNotValidYet — nbf из будущего: чаще всего — часы клиента и сервера разошлись, а вы поставили nbf «на всякий случай». Отдельный кластер — 200 при ожидаемом 401: гвард не стоит на группе (api.Use(Auth()) забыт, звено повешено после регистрации маршрутов), или проверка только «есть ли заголовок» без ParseWithClaims. Верный end-to-end тест — curl: curl -s -X POST -d "..." localhost:8080/api/v1/login | jq -r .access_token — положите токен в переменную, curl -H "Authorization: Bearer $TOKEN" localhost:8080/api/v1/todos — и вы должны увидеть 200; повторите с усечённым токеном и получите 401 с UNAUTHORIZED. И помните про WWW-Authenticate: Bearer в ответе 401 — стандарт его просит, и клиенты по нему понимают, что нужно идти за токеном.