Параметры верификации: algorithms, audience, issuer, clockTolerance

При проверке JWT в библиотеке jose основной механизм строится вокруг функции jwtVerify, которая принимает токен, ключ верификации и объект параметров контроля. Эти параметры определяют строгие правила допустимости токена: алгоритмы подписи, целевую аудиторию, издателя и допустимую погрешность времени.

algorithms ограничивает список допустимых криптографических алгоритмов, которые могут использоваться для проверки подписи JWT. Это один из ключевых элементов защиты от атак, связанных с подменой алгоритма (algorithm confusion attack).

В контексте jose проверка выглядит следующим образом:

  • токен содержит заголовок alg, указывающий алгоритм подписи
  • библиотека сравнивает его с разрешённым списком
  • при несоответствии верификация немедленно отклоняется

Типичный набор значений:

  • HS256, HS384, HS512 — HMAC-алгоритмы
  • RS256, RS384, RS512 — RSA-подпись
  • ES256, ES384, ES512 — ECDSA
  • EdDSA — Ed25519/Ed448

Использование строгого списка предотвращает ситуацию, когда токен, подписанный менее безопасным алгоритмом, принимается системой из-за отсутствия ограничений.

Пример:

import { jwtVerify } from 'jose'

const { payload } = await jwtVerify(token, key, {
  algorithms: ['RS256']
})

Любой токен с другим алгоритмом будет отклонён ещё до проверки подписи.

Параметр audience

audience (или aud) определяет, для кого предназначен токен. Это поле используется для ограничения области применения JWT и предотвращения его использования в чужих сервисах.

Структура поля может быть:

  • строка (один получатель)
  • массив строк (несколько допустимых получателей)

При верификации выполняется строгая проверка совпадения значений aud в payload токена с заданным значением параметра.

Особенности поведения:

  • при отсутствии совпадения токен считается недействительным
  • при отсутствии поля aud в токене также возникает ошибка (если аудитория задана в параметрах)
  • сравнение строгое, без частичных совпадений

Пример:

const { payload } = await jwtVerify(token, key, {
  audience: 'api.service.internal'
})

Либо вариант с несколькими аудиториями:

const { payload } = await jwtVerify(token, key, {
  audience: ['api.service.internal', 'api.service.backup']
})

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

Параметр issuer

issuer (iss) определяет издателя токена. Это идентификатор системы, которая сформировала и подписала JWT.

В процессе проверки значение из токена сравнивается с ожидаемым:

  • полное совпадение строки обязательно
  • несовпадение приводит к отклонению токена

Этот параметр часто используется в системах с централизованной аутентификацией, где важно различать источники токенов.

Пример:

const { payload } = await jwtVerify(token, key, {
  issuer: 'auth.company.internal'
})

При этом поле iss в самом токене должно быть строго:

{
  "iss": "auth.company.internal"
}

Использование issuer снижает риск принятия токена, выпущенного сторонней или тестовой системой.

Параметр clockTolerance

clockTolerance определяет допустимую погрешность времени при проверке временных полей JWT:

  • exp (expiration time)
  • nbf (not before)
  • iat (issued at)

Даже при синхронизации серверов возможны небольшие расхождения системного времени. clockTolerance компенсирует эти расхождения.

Значение задаётся в секундах.

Поведение:

  • если токен истёк, но разница меньше допустимого значения — токен считается действительным
  • если токен ещё не активен (nbf), но время входит в диапазон допуска — он принимается

Пример:

const { payload } = await jwtVerify(token, key, {
  clockTolerance: 30
})

В этом случае допускается отклонение времени на 30 секунд в обе стороны.

Совместное использование параметров

В реальных сценариях параметры комбинируются, формируя строгую модель проверки:

const { payload } = await jwtVerify(token, key, {
  algorithms: ['RS256'],
  audience: 'api.service.internal',
  issuer: 'auth.company.internal',
  clockTolerance: 15
})

Такая конфигурация задаёт одновременно:

  • допустимый алгоритм подписи
  • конкретного получателя токена
  • доверенного издателя
  • временную погрешность

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

Оглавление