Безпека API і токени
Коротке резюме
Безпека API - це сукупність механізмів автентифікації, авторизації, криптографічного захисту, анти-зловживань і спостережуваності, яка забезпечує, що запит виконує очікуваний суб'єкт до очікуваного ресурсу в очікуваному контексті. Ключовий артефакт - токен (або підпис запиту), що доводить право на виклик. Хороша архітектура спирається на короткоживучі токени, чіткі скоупи, мінімальні привілеї, захист від повторів, rate limiting і операційні процедури (ротації, аудит, інциденти).
Моделі автентифікації API: коли і що вибирати
API-ключ (статичний секрет)
Простий для B2B-інтеграцій і низькоризикових сценаріїв. Не несе контексту, вимагає зберігання на стороні сервісу.
Використовуйте тільки з IP/ASN allow-list, фіксованими квотами, коротким TTL і ротаціями.
OAuth 2. 1 / OIDC
Стандарт для користувацьких і партнерських інтеграцій: access token (короткоживучий) + refresh token (ротація) + скоупи.
Public-клієнти - з PKCE; confidential-клієнти - з клієнтським секретом/mTLS.
Client Credentials (m2m)
Mashina→mashina: access token для сервісів за строго заданими скоупами і audience, часто без refresh (отримання заново).
mTLS (взаємний TLS)
Прив'язує ідентичність до каналу. Ідеально для високоризикових або платіжних інтеграцій (PoP поверх TLS).
Може поєднуватися з OAuth (токени тільки по mTLS-клієнтам).
Підписи запитів (HMAC/EdDSA)
Коли потрібен незалежний від транспорту PoP: заголовок підпису, timestamp і nonce. Зручно для вебхуків та офлайн-перевірки.
Формати і типи токенів
JWT (JWS, підписані)
Самодостатні, перевіряються локально; обов'язкові'iss','sub','aud','exp','iat','jti','scope'.
Ризик - відгук складніший: використовуйте короткі TTL (5-15 хв) + список відкликаних'jti'при інцидентах.
JWE (зашифровані JWT)
Потрібні, якщо payload чутливий (PII). Вартість - вище складність і накладні витрати.
Reference tokens
Непрозорі ідентифікатори, перевіряються через introspection у Authorization Server - простіше відгук/централізація.
PoP/DPoP
Прив'язка токена до ключа клієнта або до TLS-сесії, знижує цінність вкраденого токена.
Вміст токена: мінімально достатньо
Рекомендовані клейми (JWT):- «iss» (issuer), «sub» (subject), «aud» (цільова система/ресурс), «exp» (термін), «iat», «nbf» (опціонально), «jti».
- 'scope '/' permissions'( мінімально необхідні),'tenant'( для багатотенантних),'device _ compliant '/' amr'( метод аутентифікації),'ip '/' asn'( якщо застосовується до політики).
- Короткі TTL для access (5-15 хв), refresh - 12-48 год (з обертовою ротацією).
- Аудиторія ('aud') - строго конкретний ресурс, інакше токен «багаторазовий».
- Скоупи - дія і об'єкт (наприклад,'payments:withdraw. read`).
- Розмір - ≤ 2-4 KB для заголовків і проксі; інакше можливі проблеми з гейтвеями.
Авторизація та політики
RBAC+ABAC: роль + контекст (організація, гео, ризик, стан пристрою).
PEP/PDP: перевірка токена і прийняття рішення на API-шлюзі/проксі (Envoy/OPA) до програми.
Декларативні правила: зберігати в Git, проходити policy-tests в CI.
rego package policy. withdraw
default allow = false
allow {
input. token. aud == "wallet-api"
input. token. scope[_] == "payments:withdraw. create"
input. device. compliant == true input. risk. score < 70
}Підпис запитів (HMAC) і анти-replay
Коли потрібно: вебхуки, інтеграції без OAuth, подвійна перевірка критичних операцій.
Схема заголовків (приклад):
X-Client-Id: <id>
X-Timestamp: 2025-11-05T13:20:10Z
X-Nonce: 4d1f...a2
X-Signature: base64(HMAC_SHA256(secret, method + "\n" + path + "\n" + sha256(body) + "\n" + timestamp + "\n" + nonce))- Відхиляти запити з розсинхроном часу> ± 300 с.
- Nonce зберігати 5-15 хв і не приймати повтори (replay-кеш).
- Підписувати канонізоване подання запиту (метод, шлях, query, хеш тіла).
Ідемпотентність і транзакційний захист
Idempotency-Key для операцій списання/виплати/створення: однаковий ключ → один і той же ефект.
Термін життя ключа - ≥ час бізнес-таймауту (зазвичай 24-72 год).
Логіка на стороні сервера: порівняти параметри запиту з раніше зафіксованими для цього ключа.
Браузерні та мобільні клієнти
PKCE обов'язково (public-клієнти).
Refresh-токен в браузері - уникати; якщо потрібен - ROTATION + реагування на повтор (replay-детект).
Зберігання: session storage > local storage; краще - за токени відповідає backend for frontend (BFF).
SameSite, Secure, HttpOnly для cookie; CORS - явні allow-lists, заголовки і методи; preflight-кешувати безпечно.
m2m і високоризиковані інтеграції
mTLS + OAuth2 Client Credentials з скоупами і'aud'.
IP/ASN allow-list на гейтвеї.
PoP/DPoP або HMAC-підписи поверх TLS для критичних операцій.
Квоти і rate limits на організацію/клієнта/ключ.
Ротації, відкликання та реагування на інциденти
Ротація секретів і ключів підпису (JWKS): за розкладом + примусово при інциденті.
Dual-key rollout: публікуйте нову ключову пару заздалегідь (kid2), підпишіть токени їй, тримайте стару (kid1) для валідації до вичерпання TTL.
Refresh-rotation: кожен обмін refresh → новий токен, старий негайно стає недійсним; повтор - сигнал компрометації.
Revocation: для JWT - списки відкликаних'jti'на короткий термін; для reference токенів - негайне блокування на AS.
Сценарії break-glass: тимчасові статичні креди з мінімальними правами і жорстким TTL, фіксуйте в журналі.
Rate limiting, bot-захист і захист від перебору
Тришарові ліміти: per-key/per-IP/per-організація.
Burst + sustained: токен-бак/ковзне вікно.
Складні перевірки: device fingerprint, поведінкові сигнали, geo/ASN аномалії, CAPTCHA тільки для UI.
Lockout/slowdown при переборі підпису/НМАС і неуспішних спробах автентифікації.
Логування, метрики та SLO
Мінімальний набір логів: `request_id`, `client_id`, `sub`, `aud`, `scope`, `decision`, `reason`, `jti`, `ip`, `asn`, `latency`, `quota_state`.
Метрики:- Успішність валідації токенів (%), p95 часу верифікації.
- Частота replay-відхилень, дублікатів Idempotency-Key.
- Частка запитів з PoP/DPoP/mTLS.
- Помилки'aud/scope', що минули'exp', зрушення часу (NTP).
- Доступність Auth/AS ≥ 99. 95 %/міс; p95 introspection ≤ 50 мс.
- Нуль токенів з TTL <60 c в проді (охоронна метрика).
- Менше 0. 1% помилок'aud/scope'в день (якість інтеграцій).
Конфігураційні приклади
Envoy: перевірка JWT і audience
yaml http_filters:
- name: envoy. filters. http. jwt_authn typed_config:
providers:
as:
issuer: https://auth. example. com/
audiences: ["wallet-api"]
remote_jwks:
http_uri:
uri: https://auth. example. com/.well-known/jwks. json cluster: jwks_cluster cache_duration: 600s rules:
- match: { prefix: "/v1/withdraw" }
requires:
provider_and_audiences:
provider_name: as audiences: ["wallet-api"]NGINX: mTLS к backend
nginx proxy_ssl_server_name on;
proxy_ssl_name wallet. internal;
proxy_ssl_certificate /etc/nginx/mtls/client. crt;
proxy_ssl_certificate_key /etc/nginx/mtls/client. key;
proxy_ssl_trusted_certificate /etc/nginx/mtls/ca. crt;
proxy_ssl_verify on;
proxy_ssl_verify_depth 2;Приклад заголовка підпису (вебхуки)
X-Signature: t=1730803210,n=ac12...,s=base64(HMAC_SHA256(secret, "POST\n/webhook\nsha256(body)\n1730803210\nac12..."))Сервер відхиляє, якщо't'старше 300 c,'n'вже зустрічався, або's'не б'ється.
Захист даних і приватність
Мінімізуйте клейми (особливо PII) і термін життя.
Шифруйте чутливі клейми (JWE) для сторонніх інтеграцій.
Mask/DLP в логах: не логувати тіла з PAN/PII, токени - тільки'kid '/прапори, не сам секрет.
Типові помилки
Довгоживучі access-токени і «вічні» refresh.
Відсутність'aud '/' scope'→ токени багатоцільові.
Підпис вебхуків без «timestamp »/« nonce».
Перевірка JWT тільки в додатку, а не на гейтвеї (PEP).
Відсутність ротацій і dual-key rollout.
CORS «» і дозволені небезпечні методи без контролю заголовків.
Зберігання токенів в'localStorage'без BFF.
Дорожня карта впровадження
1. Інвентаризація API і класифікація (публічні/партнерські/внутрішні, чутливість).
2. Вибір моделі AuthN: OAuth2/OIDC для користувацьких, mTLS + Client Credentials/HMAC для m2m.
3. Токени: короткі TTL, строгий'aud', скоупи, DPoP/PoP для критичних операцій.
4. PEP на гейтвеї: валідація JWT, підписи і rate limits до програми.
5. Анти-replay та ідемпотентність: timestamp/nonce/Idempotency-Key.
6. Ротації та JWKS: dual-key, автоматизація та алертинг.
7. Спостережуваність: метрики/SLO, журнали доступу, UEBA-сигнали.
8. Навчання: відзв ключа підпису, витік refresh, перевантаження квот.
Специфіка для iGaming/фінтех
Платежі/виплати: тільки mTLS + PoP/HMAC, строгі скоупи ('withdraw. create'), idempotency обов'язковий.
Партнери (PSP/провайдери контенту): per-partner ключі/сертифікати, IP/ASN allow-list, окремі квоти і дашборди.
GDPR/PCI DSS: мінімізація клеймів, заборона PII в токенах сторонніх, логування доступу до чутливих ресурсів, регулярні access review.
Anti-abuse: поведінкові ліміти, гео-контроль, захист від бонус-аб'юзу на рівні API.
FAQ
JWT або reference token?
JWT - продуктивність і автономність; reference - централізований відгук і простота інцидент-реакції. Часто гібрид: зовнішнім - JWT, внутрішнім - reference.
Чи потрібен JWE?
Тільки якщо payload містить PII/секрети. Інакше - JWS з мінімальними клеймами.
Чи можна жити на API-ключах?
Так, але тільки з коротким TTL, строгими квотами, IP-allow-list і підписом запитів. Для користувачів - переважно OAuth/OIDC.
DPoP/PoP обов'язково?
Не завжди. Але для high-risk операцій (платежі, висновки) - вкрай бажаний.
Підсумок
Надійна безпека API будується на короткоживучих токенах, точних скоупах і аудиторії, захищених каналах (TLS/mTLS), підписи запитів і суворої анти-replay захисту, посилених лімітами і спостережуваністю. Додайте автоматизовані ротації, dual-key rollout і політичний контроль на гейтвеях - і ваш API стане стійким до витоків, повторів і зловживань, зберігши при цьому високу продуктивність і керованість.