JWKS: публичные ключи по URL

Документ — объект с единственным полем keys: массивом JWK, по одной записи на каждый публичный ключ. У RSA-ключа поля такие: kty со значением RSA — тип ключа; use sig — ключ для подписей, а не для шифрования; alg RS256 — ожидаемый алгоритм; kid — строка-идентификатор, которую вы придумываете сами и которая связывает токен с записью; n — модуль в base64url без паддинга; e — экспонента, для стандартной 65537 это три символа AQAB. kid — самая нагруженная деталь: при выпуске токена сервер кладёт его в header, а keyfunc проверяющего ищет запись с таким же kid в массиве. Без kid проверяющему пришлось бы перебирать ключи и сверять подпись каждым — работает, но медленнее и без диагностичности: ошибка «нет ключа для 2026-01-primary» говорит всё сразу. Имя kid я делаю из даты и роли ключа — так ротация читается в логах сама, без отдельной документации.

Протокол ротации строится на одном факте: старый ключ нужен до тех пор, пока жив хоть один токен, им подписанный. Поэтому новый ключ появляется рядом со старым, а не вместо него. Последовательность такая: генерируем новую пару, добавляем публичный в массив keys вторым элементом — документ теперь отдаёт оба; переключаем выпуск на новый kid, дописав его в header новых токенов; ждём exp последнего токена, подписанного старым; убираем старую запись. Проверяющие при этом не делают ничего: они увидят новый kid, не найдут его в кэше, обновят JWKS и продолжат работу. Вся схема опирается на то, что оба состояния документа — до и после — валидны: промежуточных состояний, где ключа нет, а токены с ним ещё ходят, быть не должно. Именно это условие нарушают чаще всего, и следующим блоком — о последствиях.

kid приходит в header токена, а header — часть входных данных, контролируемая клиентом. В коде выше это безопасно: kid ищется в map, промах даёт ошибку. Проблемы начинаются там, где kid уходит дальше: в SQL-запрос с конкатенацией строк, в путь к файлу ключа на диске, в лог без экранирования. Атакующий подставляет kid с кавычкой и логикой внутри и добивается либо чтения чужой записи, либо выхода за пределы каталога. Правило то же, что для любого пользовательского ввода: kid — строка для поиска в заранее загруженном наборе, а не аргумент запроса. Если ключи живут в базе, сравнение делает параметризованный запрос: незнакомый kid возвращает пустой результат и обычный отказ 401, без побочных эффектов. Три строки кода — и целое семейство атак закрыто.

Ходить за JWKS на каждый запрос — значит добавлять сетевой прыжок к каждому логину и ставить собственную доступность в зависимость от чужого эндпоинта. Правильный режим: кэш в памяти процесса, обновление по событию. Событие — неизвестный kid: токен пришёл, kid в кэше нет, проверяющий перечитывает JWKS — раз, и не чаще, чем раз в несколько секунд, чтобы чужой сбой не превратить в собственный шторм повторов. Google и Auth0 дополнительно публикуют Cache-Control, и уважающий его клиент обновляет документ ещё и по расписанию. Спорный вопрос — что делать при недоступности эндпоинта, когда кэш уже устарел: я держу устаревшую копию и продолжаю проверять ею, потому что альтернатива — отключить весь вход из-за одной сети. Исключение — после компрометации ключа: тогда устаревший кэш опустошается принудительно, и никакая доступность не важнее отзыва. Общий кэш с TTL в Redis строится на той же механике сроков, что разобрана в уроке про TTL курса go-redis.

Разбор одного инцидента: identity-сервис провёл ротацию по правилам — новый ключ в JWKS, выпуск переключён, старая запись держится до exp. Через месяц у одного партнёра посыпались 401 на заведомо свежих токенах, а вскоре выяснилось: их сервис читал jwks.json один раз при старте процесса, в ноябре. Новый kid в их кэше так и не появился, и часть токенов отбрасывалась до ближайшего перезапуска. Сначала обвиняли наш эндпоинт, но его лог показал: за неделю ноль запросов с их адреса. Вывод одинаков для обеих сторон: у проверяющего обязано быть обновление по неизвестному kid, а у выпускающего — алерт на странный трафик, когда одни клиенты перечитывают документ постоянно, а другие не приходят вовсе. Чек-лист из урока про лучшие практики вырос из историй вроде этой.

Скажу непопулярное: если выпускающий сервис один, а проверяющих два и все они живут в одном репозитории, JWKS — оверинжиниринг. Эндпоинт, кэш, обновление по kid, тесты на оба состояния документа — неделя работы и постоянная забота ради экономии одного PEM-файла в конфиге. Файл у проверяющих работает, пока их мало и деплоятся они из одного CI. Граница, за которой я передумываю: проверяющих больше трёх, они в разных командах или вообще чужие компании — тогда рассылка файлов перестаёт масштабироваться, и JWKS окупает себя за первую же ротацию. Между этими состояниями лежит серая зона, и решение там принимается не по красоте архитектуры, а по ответу на простой вопрос: кто звонит в поддержку, когда ключ сменился, а у кого-то остался старый?