Ротація ключів і токенів

1) Навіщо потрібна ротація

Ключі і токени неминуче «старіють»: експозиція в логах/бекапах, інсайдерські ризики, вразливості бібліотек, витоки у партнерів. Ротація знижує «час життя ризику» і дає керованість при інцидентах. Мета - побудувати передбачувані цикли ротації і механізми швидкого відкликання без простою.

2) Область: що саме ротуємо

Ключі підпису/шифрування: JWT (JWS/JWE), OAuth/OIDC, SAML, вебхуки (HMAC), ліцензії.
Секрети інтеграцій: API-ключі, client secret, паролі тех. користувачів.
TLS/mTLS: серверні/клієнтські сертифікати, кореневі/проміжні CA.
Ключі даних: KEK/CMK в KMS/HSM, DEK (envelope encryption).
Токени: access/refresh, service-to-service (mTLS, HMAC), short-lived session.

3) Зберігання, версії, мітки

KMS/HSM/Vault як джерело правди. Заборонено зберігати приватні ключі в git/ENV/файлах образів.
Версіонування: 'key _ id '/' version'+ мітки: `purpose=jwt-sign`, `env=prod`, `alg=ES256`, `created_at`, `rotates_at`.
Політики доступу: принцип мінімально необхідних прав (least privilege), поділ обов'язків (SoD).
Аудит: хто створив/читав/підписував; незмінні журнали.

4) Базові патерни ротації

4. 1 Вікна, що перекриваються (graceful rollover)

Новий ключ → публікуємо в JWKS/поширюємо сертифікат.
Вікно перекриття: валідація старими і новими ключами, підпис - тільки новим.
Після закінчення grace-періоду - видаляємо старий з довіреного набору.

4. 2 Подвійний випуск (dual-run)

Короткий період, коли частина інстансів підписує старим, частина - новим (для великих флітів).
Вимагає строго синхронізованого JWKS і моніторингу частки валідацій по'kid'.

4. 3 Rotate-on-schedule vs rotate-on-use

За розкладом: раз на N днів/тижнів (ключі підпису, TLS).
При використанні: refresh-токени - одноразові, на кожен обмін випуск нового («ковзна» ротація).

5) JWT/JWKS: Практика

5. 1 Заголовки та ідентифікатори

Використовуйте'kid'в JWS-заголовку для вибору ключа верифікації.
Мінімум клаймів, коротке'exp', коректні'aud/iss/nbf'.

json
{ "alg": "ES256", "kid": "jwt-2025-10", "typ": "JWT" }

5. 2 Публікація JWKS

JWKS повинен містити всі активні ключі перевірки (старий + новий у вікно grace).
Кешування JWKS у клієнтів: короткий TTL (наприклад, 5-15 хв).
При компрометації - видалити скомпрометований ключ з JWKS (різко), форс-інвалідація кешу.

json
{
"keys": [
{ "kty":"EC","crv":"P-256","kid":"jwt-2025-10","use":"sig","alg":"ES256","x":"...","y":"..." },
{ "kty":"EC","crv":"P-256","kid":"jwt-2025-07","use":"sig","alg":"ES256","x":"...","y":"..." }
]
}

5. 3 Каденс і терміни

Підпис JWT: ротація ключа кожні 3-6 міс (або частіше для high-risk).
'exp'access-токена: 5-30 хв; refresh - 7-30 днів (з «rotate-on-use»).
Примусове «склеювання» з PoP/DPoP (див. § 8) для зниження ризику викрадення.

6) Ротація HMAC (вебхуки/підписи)

Зберігайте активний і канарський секрети; приймайте підписи обома.
Заголовки: `X-Signature` + `X-Timestamp`; обмеження вікна ± 300с.
Повне відключення старого - після того, як відправник підтверджено переключився.
Для партнерів: публікуйте дату-час перемикання і endpoint перевірки.

7) TLS/mTLS і ланцюжки довіри

ACME/auto-renew для публічних серверних сертифікатів (Let's Encrypt або корпоративний CA).
mTLS: короткі клієнтські сертифікати (7-30 днів), автоматична ротація по каналах (SPIFFE/SPIRE/mesh).
Ротація проміжного/кореневого CA - тільки через перекриваються якоря довіри (trust bundle) і тривалий canary.
Слідкуйте за OCSP/CRL і clock-skew. У логи - причини відмови валідації.

8) PoP/DPoP і зв'язка token↔klyuch клієнта

DPoP (Demonstration of Proof-of-Possession): токен прив'язаний до public-key клієнта; знижує ризик replay.
Ротація ключа клієнта = випуск нового DPoP-ключа, токенів - на короткий термін.
Для сервіс-к-сервісу кращий mTLS (пристрій/воркер «несе» ключ в HSM/TPM).

9) Refresh-токени: rotate-on-use

Одноразові refresh-токени: кожен обмін → новий refresh + access.
Список відкликаних'jti '/' sid'зберігати з TTL = термін життя refresh.
Детект повторного використання (ре-плей): негайний відгук сесії/пристрою, алерт.

10) Відгук і списки блокування

JWT без інтроспекції: використовуйте короткий'exp'+ «чорні списки»'jti'для критичних кейсів (локально/в Redis, шардування по хешу).
OAuth introspection: централізований сервер статусів; кешуйте «active = false/true» з коротким TTL.
API-ключі: зберігайте хеш ключа (як паролі), мітки власника/тенанта, scope, дата створення/останнього доступу; відгук - миттєво.

11) Ключі даних: envelope-шифрування

CMK/KEK (KMS/HSM) захищає DEK; ротація CMK відбувається без перерозкриття даних: пере-wrap DEK.
DEK для кожного об'єкта/тенанта/партії; KDF/HKDF для похідних ключів.
Політики знищення (crypto-shredding): видалення KEK = нечитабельність даних при компрометації.

12) Процедури інцидентів (компрометація)

1. Заморозити: відключити випуск токенів на скомпрометованому ключі, перевести видачу на новий.
2. Відкликати: видалити'kid'з JWKS, відкликати сертифікати (OCSP/CRL), заблокувати API-ключі за списком.
3. Скоротити TTL: тимчасово зменшити'exp'токенів, посилити перевірку PoP/DPoP.
4. Примусовий logout: інвалідувати сесії (revoke'sid '/' jti').
5. Форензика та звітність: таймлайни, охоплення, хто/що постраждав; оновити плейбуки.

13) Пайплайн і rollout

13. 1 Генерація та публікація

Генеруйте ключі в HSM/KMS; експорт приватного ключа - заборонено.
Автоматична публікація JWKS/сертифікатів з верифікацією та тестами.
Канарний реліз: 1-5% клієнтів → 100%.

13. 2 Контроль здоров'я

Метрики: частка валідацій за «kid», помилки підпису/сертифіката, дрейф годинників.
Алерти: сплеск 401/403 через підпис, OCSP/CRL недоступний, що закінчуються сертифікати (T-30/T-7/T-1).

14) Конфіги і приклади

14. 1 Приклад політики Vault/KMS (псевдо)

hcl path "transit/keys/jwt-prod" {
capabilities = ["read," "update," "list"] # signature/rotation
}
path "transit/keys/jwt-prod/rotate" {
capabilities = ["update"]
}

14. 2 Приклад плану ротації JWT

T0: create a new version of the key (kid = jwt-2025-10), add to JWKS
T0 + 15m: start signing with a new kid; validate with old and new
T0 + 7d: remove old kid from JWKS
T0 + 30d: delete old private key from KMS (schedule purge)

14. 3 Envoy: примусове оновлення JWKS (псевдо)

yaml jwt_authn:
providers:
oidc:
issuer: https://auth. example. com/
remote_jwks:
http_uri:
uri: https://auth. example. com/.well-known/jwks. json cluster: jwks_cluster timeout: 2s cache_duration: 300s # короткий TTL

15) Спостережуваність і аудит

Метрики: `jwt_verify_fail_total{reason}`, `jwks_refresh_total`, `jwks_kid_share{kid}`, `token_revoked_total`, `refresh_rotations_total`, `dpop_fail_total`.
Логи: `kid`, `jti`, `sid`, `reason`, `client_id`, `tenant`, `trace_id` (без PII).
Дашборди: карта часток'kid', що закінчуються сертифікати, частота відкликання, невалідні підписи по регіонах.

16) Антипатерни

Довгоживучі JWT без відкликання і без короткого'exp'.
Відсутність'kid'і «ручний» підбір ключа перевірки.
Зберігання секретів в ENV/k8s-Secret без KMS і без шифрування на рівні etcd.
Неротаційні refresh-токени; повторне використання refresh без детекту.
Єдиний глобальний API-ключ «на всіх».
«Тихий» випуск нових ключів без публікації JWKS і моніторингу.
Нульові вікна перекриття (миттєва заміна) → масові 401/403.

17) Специфіка iGaming/фінансів

Регулятори та аудит: незмінювані логи ротацій/відгуків; доказовість часу і акторів.
Партнерські PSP/KYC: окремі ключі на партнера/юрисдикцію; швидкий відгук при порушеннях SLA/безпеки.
Багатоарендність: per-tenant API-ключі зі scope; ізоляція ключів брендів/регіонів.
Високий ризик: PoP/DPoP для критичних операцій, короткі'exp', mTLS між внутрішніми сервісами.
Backoffice: SSO/OIDC, короткі сесії, апаратні токени (FIDO2), повсюдний rotate-on-schedule.

18) Чек-лист prod-готовності

• Всі приватні ключі в KMS/HSM/Vault; заборонено експорт.
• JWKS публікується і кешується з коротким TTL; у заголовках JWT є'kid'.
• План ротації з вікном, що перекривається, і автоматичним rollout.
• Refresh-токени одноразові; список відкликаних'jti'з TTL.
• HMAC-секрети: активний + канарний; прийом обома; оголошено T-час перемикання.
• TLS/mTLS: auto-renew, алерти T-30/T-7/T-1, trust bundle для зміни CA.
• Envelope-шифрування: KEK/CMK ротуються без простою, DEK per-об'єкт/тенант.
• Метрики/алерти за підписом, JWKS, відгуками; дашборди'kid'-долей.
• Плейбук інцидентів (компрометація) і регулярні навчання.
• Тести canary і реплей валідацій з новими ключами/СА.

19) TL; DR

Тримайте ключі в KMS/HSM, підписуйте JWT з'kid'і публікуйте JWKS. Ротуйте ключі та сертифікати з перекриттям, стежте за частками валідацій по'kid'. Refresh - rotate-on-use і короткі'exp'; для критичних операцій - PoP/DPoP і mTLS. Для даних використовуйте envelope-шифрування з ротацією KEK без простою. Впроваджуйте метрики/алерти, плейбуки інцидентів і регулярні канарські ротації.