Автентифікація API: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT - стандарт для клієнтських додатків і серверних інтеграцій зі складною авторизацією (scopes/roles/tenants), SSO і короткими TTL токенів.
HMAC-підписи - кращий вибір для вебхуків і простих партнерських викликів «server→server» з детермінованою перевіркою і жорстким захистом від replay.
Посилюйте безпеку: mTLS або DPoP (sender-constrained tokens), короткі TTL (5-15 хв), ротація ключів (JWKS), refresh-токени з ротацією/anti-reuse, сувора валідація'aud/iss/exp/nbf/kid'і policy-as-code на gateway.

1) Карта рішень: що де застосовувати

2) OAuth2/OIDC: потоки та клієнти

2. 1 Потоки

Authorization Code + PKCE (Web/Mobile): захищає код авторизації від перехоплення.
Client Credentials: server↔server без користувача; scopes - мінімально необхідні.
Device Code: для пристроїв без браузера.
Refresh Token: тільки для довірених клієнтів; ротуйте і вмикайте reuse detection.

2. 2 Клієнтські типи

Confidential (сервери, BFF): зберігають секрети; використовуйте mTLS.
Public (SPA/mobile): секрет зберігати не можна → PKCE, DPoP, короткі TTL і обмежені scopes.

3) JWT: структура, терміни, верифікація

3. 1 Поля (claims)

Обов'язкові: 'iss','sub','aud','exp','iat','nbf','jti','scope '/' permissions','tenant'( якщо мультиаренда),'kid'.

3. 2 Терміни життя

Access token: 5-15 хвилин.
Refresh token: дні/тижні, ротуємо при кожному обміні; при повторній подачі старого - блокуємо сесію.
Clock skew: допуск ≤ 60 сек.

3. 3 JWKS і ключі

Зберігання ключів в KMS/Vault,'kid'обов'язковий.
Два активних ключа (rolling), перевипуск раз в 60-90 днів або при інциденті.
Кеш JWKS на gateway ≤ 5 хвилин, з авто-інвалідацією.

3. 4 Верифікація на gateway/сервісах

Звіряйте: підпис,'aud'( допущені сервіси),'iss','exp/nbf', список блокувань (revocation).
Не довіряйте полям з тіла без перевірки підпису; ігноруйте'alg = none'.

Authorization: Bearer <JWT>
X-Trace-Id: <uuid>

4) Прив'язка токена до клієнта: mTLS, DPoP

mTLS (TLS клієнтські сертифікати): токен видається і валідується тільки при наявності клієнтського сертифіката → токен марний поза зв'язкою «ключ + сертифікат».
DPoP (Demonstration of Proof-of-Possession): клієнт підписує кожен запит одноразовим ключем → захист від replay і крадіжки токена в публічних клієнтах.
Для критичних маршрутів (платіжні мутації) - вимагати один з механізмів.

5) Авторизація: scopes, roles, ABAC

Scopes - мінімальні дії ('payments:write`, `payouts:status:read`).
Roles - агрегати для адмінок; не використовуйте їх безпосередньо без scopes.
ABAC - атрибути в токені ('tenant','country','kyc _ level','risk _ flags') → політики на gateway/OPA.
Політика на рівні маршруту/поля (GraphQL) і на рівні доменної операції (REST/gRPC).

6) HMAC-підписи: вебхуки та партнери

6. 1 Концепт

У кожної інтеграції - власний секрет.

Підпис над канонічним рядком: `timestamp + "\n" + method + "\n" + path + "\n" + sha256(body)`

X-Signature: v1=base64(hmac_sha256(secret, canonical_string))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF...

Вікно часу: ≤ 300 сек; запити з простроченим/майбутнім'X-Timestamp'відхиляти.
Ідемпотентність: зберігайте'X-Event-Id'на TTL (24 год) - відкидайте дублікати.

6. 2 Кращі практики

Секрети в KMS/Vault, ротація кожні 90 днів.
Для публічних клієнтів HMAC не підходить (секрет витікає); Використовуйте OAuth2/DPoP.

7) Захист від replay, brute force і витоків

Nonce/' jti'для чутливих операцій; чорний список використаних ідентифікаторів.
Rate/quotas: за ключем/клієнтом/тенантом/маршрутом; «дорогі» операції - окремі квоти.
IP/ASN/Geo allow-lists для партнерів і вебхуків.
Content-type allow ('application/json'), ліміт розміру тіла.
Маскування PII в логах; заборона логувати токени/секрети.

8) Помилки та відповіді (єдиний формат)

json
{
"error": "invalid_token",
"error_description": "expired",
"trace_id": "4e3f-..."
}

• «401» - ні/невалідний токен (WWW-Authenticate).
• «403» - недостатньо прав (scope/ABAC).
• '429'- ліміти/квоти.
• gRPC: `UNAUTHENTICATED`/`PERMISSION_DENIED`/`RESOURCE_EXHAUSTED`.

9) Політики термінів і сесій

Access ≤ 15 хв; Refresh - ротація + reuse detection (подали старий - відгук сесії).
Вебхукі HMAC: TTL підписи ≤ 5 хв; повторна доставка з експоненціальним backoff.
Відгук сесії/ключа → негайне потрапляння в revocation list (кеш на gateway ≤ 1 хв).

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

Кореляція по'trace _ id '/' span _ id'.
Метрики: auth success rate,'401/403/429', латентність OIDC/JWKS, частота ротацій, reuse refresh, частка DPoP/mTLS трафіку.
Аудит-лог: «хто, коли, з яким'sub/tenant/scope'викликав що», зміни ключів/секретів, провалені підписи HMAC.

11) Вбудовування в API Gateway

JWT-валідація (JWKS кеш) і OPA/ABAC на шлюзі.
mTLS профілі для довірених клієнтів/партнерів.
HMAC-верифікація вебхуків на edge (до внутрішніх сервісів).
Rate/Quota поліси, circuit-breaker на OIDC-провайдера (кешувати JWK).
Feature-flags: швидке відключення клієнта/ключа, зміна алгоритму підпису.

12) Міні-сніпети

Псевдо: верифікація JWT

pseudo jwks = cache. getOrFetch(iss + "/.well-known/jwks. json")
key = jwks[kid]
assert verify_signature(jwt, key)
assert aud in ALLOWED_AUDIENCES and iss in TRUSTED_ISSUERS assert now in [nbf-60s, exp+60s]

Псевдо: перевірка HMAC вебхука

pseudo canonical = timestamp + "\n" + method + "\n" + path + "\n" + sha256(body)
sig = base64(hmac_sha256(secret, canonical))
assert abs(now - timestamp) <= 300 assert not seen(event_id)
assert timingSafeEqual(sig, header["X-Signature"].split("v1=")[1])
markSeen(event_id, ttl=86400)

Приклад scope-політики (OPA/Rego ідея)

rego allow {
input. jwt. scope[_] == "payments:write"
input. jwt. tenant == input. route. tenant
}

13) Плейбуки інцидентів

Витік приватного ключа/JWT-підписувача: перевипуск ключів, оновлення JWKS, негайне відключення старого ('kid'→ deny), інвалідація refresh, примусовий logout.
Підміна вебхуків: ротація секретів, IP allow-list, посилення вікна'X-Timestamp', повторна доставка пропущених подій.
Replay/брутфорс: включити DPoP/mTLS на критичних маршрутах, звуження квот, тимчасові блоки по IP/ASN, включити'jti'-блокліст.
Outage OIDC: деградація кешованих токенів (grace), circuit-breaker провайдера, повідомлення клієнтів.

14) Чек-листи впровадження

• OAuth2: Code+PKCE (Web/Mobile), Client Credentials (server-to-server)
• TTL: Access ≤ 15 хв, Refresh з ротацією і reuse detection
• JWKS: два активних ключа, «kid», кеш ≤ 5 хв
• Вебхукі: HMAC v1,'X-Timestamp','X-Event-Id', вікно ≤ 300 сек, ідемпотентність
• Sender-constrained: mTLS/DPoP на критичних маршрутах
• ABAC/OPA: scopes + tenant/risk в політиках шлюзу
• Rate/Quota и 429; IP/ASN allow-lists для партнерів
• Аудит та алерти (401/403/429, reuse refresh, підписи HMAC)

• Не логувати токени/секрети/повні тіла карт
• Маскування PII; DSAR підтримка; термін зберігання логів обмежений

15) Анти-патерни

'alg = none'або довіра токену без перевірки підпису/JWKS.
Довгоживучі access-токени (годинник/доба).
Один загальний HMAC-секрет на всіх партнерів.
Вебхукі без таймштампу/ідемпотентності.
Refresh-токени без ротації і без reuse detection.
Відсутність'aud '/' iss'-валідації і'kid'-ротації.
Зберігання секретів у змінних оточення без KMS/Vault.

16) НФТ/SLO (орієнтири)

OIDC/JWKS доступність ≥ 99. 95% (edge-кеш знижує залежність).
JWT валідація добавка на gateway ≤ 2-5 мс p95.
Помилки автентифікації («401») ≤ 0. 5% від загального трафіку (без урахування ботів).
Підписані вебхуки: частка успішно верифікованих ≥ 99. 9%, середня затримка доставки ≤ 3 с.

Резюме

Комбінуйте механізми: OAuth2/OIDC + JWT для користувачів і багатих серверних сценаріїв, HMAC для вебхуків/простих партнерів, а для критичних операцій - mTLS/DPoP. Тримайте короткі TTL, ротації ключів (JWKS), суворі політики ABAC/OPA, захищайте контури від replay і витоків, і автоматизуйте все на рівні API Gateway. Так автентифікація стане передбачуваною, масштабованою і безпечною - без компромісів для UX і монетизації.