JWT (JSON Web Token)¶

JWT (JSON Web Token) — компактний, URL-безпечний формат представлення claims (тверджень), що передаються між двома сторонами у вигляді підписаного або зашифрованого JSON-об'єкта.

Опис¶

JWT визначено в RFC 7519. Токен складається з трьох частин, розділених крапкою: header.payload.signature. Кожна частина кодується Base64url без padding.

Header містить тип токена та алгоритм підпису:

{ "alg": "RS256", "typ": "JWT" }

Payload містить claims — твердження про суб'єкт:

{
  "sub": "user123",
  "iss": "https://auth.umtc.local",
  "aud": "wiki-api",
  "exp": 1744747200,
  "iat": 1744743600,
  "roles": ["editor", "viewer"]
}

Signature — підпис заголовка та payload приватним ключем сервера (RS256, ES256) або симетричним ключем (HS256).

Важлива відмінність: JWT — це формат, а не протокол автентифікації. JWT може використовуватися як bearer-токен в OAuth 2.0, як session-token або в будь-якому іншому контексті. Сервер перевіряє підпис та claims (термін дії exp, видавець iss, аудиторія aud) без звернення до бази даних — це головна перевага перед непрозорими session-токенами.

Ризики JWT: некоректна перевірка підпису (алгоритм none), відсутність перевірки exp та aud, зберігання токенів у localStorage (XSS). У виробничих системах рекомендовано алгоритми асиметричного підпису (RS256, ES256) та короткий термін дії (15–60 хвилин) з механізмом оновлення через refresh-token.

В контексті UMTC¶

MAS (Matrix Authentication Service) видає JWT як access-токени після успішної авторизації через OAuth 2.0. FastAPI backend UMTC Wiki перевіряє підпис кожного запиту:

# Приклад перевірки JWT у FastAPI
from jose import jwt, JWTError

async def verify_token(token: str):
    try:
        payload = jwt.decode(
            token,
            public_key,          # RSA публічний ключ MAS
            algorithms=["RS256"],
            audience="umtc-wiki"
        )
        return payload
    except JWTError:
        raise HTTPException(status_code=401)

Публічний ключ для перевірки підпису отримується з JWKS-ендпоінту MAS (/.well-known/openid-configuration → jwks_uri). Це дозволяє ротувати ключі підпису без зупинки сервісу.

Пов'язані терміни¶

• oauth2 — OAuth 2.0 використовує JWT як access-токени та ID-токени
• mtls — альтернативний механізм автентифікації на основі сертифікатів, а не токенів
• matrix — Matrix використовує JWT в деяких federation-сценаріях

Посилання¶

• RFC 7519 — JSON Web Token — специфікація JWT
• RFC 7517 — JSON Web Key (JWK) — формат публічних ключів JWKS
• jwt.io — декодер та debugger JWT