API-ключі, токени та мандати доступу: Безпечна автентифікація

Повний текст статті

💡 18+. Технічний матеріал для платформ, студій (RGS/live), агрегаторів і суміжних сервісів (джекпоти, KYC/AML). Не заклик до гри.

1) Навіщо все це: модель загроз для iGaming

Гроші та PII: компрометація ключа → фрод, витоки, штрафи.

Мережеві інтеграції: десятки зовнішніх провайдерів, різні регіони/ліцензії.

Високі ставки SLA: простий або дубль платежу - репутаційні та юридичні ризики.

Висновок: автентифікація і авторизація повинні бути «за замовчуванням безпечні», з мінімальними привілеями і жорсткою спостережуваністю.

2) Інструменти: що у нас є в арсеналі

API-ключі: статичні ідентифікатори клієнта. Проста інтеграція, високий ризик витоків.

OAuth2 (Client Credentials): короткоживучі Bearer-токени зі scope/audience.

mTLS: взаємна TLS-перевірка, сильна прив'язка клієнта до каналу.

HMAC/EdDSA підписи: криптографічна цілісність тіла запиту і захист від реплеїв (timestamp + nonce).

Proof-of-Possession: MTLS-bound токени або DPoP (підпис HTTP-запиту ключем клієнта).

JWT/PASETO: самоописні токени (бажано з коротким TTL).

RBAC/ABAC: роль/атрибут-бейзд авторизація (ОРА/рішення політик).

Тимчасові мандати доступу (delegation/STS): обмежені за часом і цілями квитки, що видаються на конкретний сценарій.

3) Базові принципи («стоп-знаки»)

1. Least Privilege: кожному ключу/токену - мінімально можливі права.

2. Short-lived by default: TTL хвилинами, не днями. Ротація - автоматична.

3. Bind to channel: прив'язка токенів до mTLS/DPoP → марні при витоку.

4. Per-brand/region: ключі/сертифікати та дозволи - на бренд/ліцензію/регіон.

5. No shared secrets в коді: секрети тільки через Vault/HSM/KMS, ні в Git/логах.

6. WORM-аудит: незмінювані логи всіх операцій/видач/ротацій.

7. Ідемпотентність на write-шляхах: будь-який повтор з тим же ключем не змінює гроші вдруге.

4) Коли використовувати що (iGaming-контекст)

Сценарій	Рекомендується
Грошові RPC (wallet authorize/settle, cashier)	mTLS + OAuth2 CC з MTLS-bound токенами; заголовки'X-Idempotency-Key','X-Trace-Id '
Вебхукі (події)	Підпис тіла HMAC/EdDSA + timestamp/nonce, allow-list джерел, ретраї з дедупом
B2B каталоги/звіти	OAuth2 CC (короткоживучі Bearer) + rate-limits
Машинне делегування (джекпот → гаманець)	STS/Token Exchange з вузькими scope і TTL ≤ 5 хв
Адмін-панель/операції	OIDC для людей + RBAC/ABAC, MFA/біометрія, «чотири ока»

5) Дизайн мандатів доступу (scopes, audience, умови)

Scope-и (приклади):

`bets:write`, `settlements:write`, `wallet:credit`, `wallet:debit`, `rg:read`, `rg:enforce`, `jackpot:trigger`.

Audience: кому адресований токен (наприклад,'aud: wallet. api`).

Constraints (fine-grained):

`brand_id`, `region`, `ip/cidr`, `time_of_day`, `rate_limit`, `max_amount`.
Зберігаються в токені (JWT claims) або у виписаному «мандаті» в Vault/STS.

6) Еталонні флоу

6. 1 Платформа ⇄ RGS: гроші по RPC

1. mTLS handshake (сертифікати per brand/region).

2. OAuth2 CC: RGS отримує'access _ token'( TTL 2-5 хв,'aud = wallet. api`, `scope=bets:write settlements:write`).

3. Запит'POST/v1/bets/authorize'з заголовками:

`Authorization: Bearer `, `X-Idempotency-Key`, `X-Trace-Id`.
4. Відповідь + запис в WORM-аудит (хто/що/коли/звідки).
5. Ротація токена безшовна, після закінчення - повтор CC.

6. 2 Вебхукі платформа → провайдер

Заголовок'X-Signature: eddsa=` или `sha256=...`, `X-Timestamp`, `X-Nonce`.

Провайдер перевіряє: вікно валідності (± 5 хв), одноразовість «nonce», підпис тіла.

При недоступності - ретрай c backoff, дедуп по'event _ id'.

6. 3 Делегування (джекпот-сервіс → гаманець)

JP викликає STS: "дай тимчасовий токен на'wallet:credit'для'player _ id = p _...', сума ≤ X, TTL 2 хв".

STS перевіряє політику/ліміти → видає мандат (вузький токен).

JP кредитує гаманець з цим токеном. Компрометувати такий токен безглуздо: короткий TTL, вузькі права, прив'язка до mTLS.

7) Конструкції запитів

7. 1 Ідемпотентність (обов'язково)


POST /v1/bets/settle
Authorization: Bearer <MTLS-bound>
X-Idempotency-Key: settle_r_8c12_1
X-Trace-Id: tr_a1b2
{
"bet_id":"b_001",  "round_id":"r_8c12",  "win":{"amount":1460,"currency":"EUR"}
}
→ 200 { "status":"credited", "settlement_id":"st_77" }
(повтор з тим же ключем → та ж відповідь)

7. 2 Підпис вебхука (HMAC)


X-Signature: sha256=BASE64(HMAC(secret, timestamp + "." + nonce + "." + body))
X-Timestamp: 1730000000
X-Nonce: 1f7a...

8) Управління секретами та ключами

Vault/HSM/KMS: генерація, зберігання, ротація, відгук.

Пер-оточення: sandbox/prod - різні корені довіри.

Пер-бренд/регіон: окремі ключі та сертифікати.

Авто-ротація: cron/оповіщення; overlap-періоди для безшовних замін.

Заборона в коді/логах: секрети не пишуться в stdout, не потрапляють в crash-репорти.

Device/Workload identity: SPIFFE/SPIRE, K8s ServiceAccount → mTLS без ручних секретів.

9) Політики авторизації (RBAC/ABAC) і OPA

RBAC: роли «rgs», «wallet», «jackpot», «reporting».

ABAC: правила "якщо'region = EU'і'brand = A'→ дозволити'wallet:credit` ≤ 10k».

OPA/REGO або аналоги: централізоване прийняття рішень, версіонування політик, сухі тести.

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

Наскрізні'trace _ id'і'client _ id'в кожному запиті/події.

Метрики: p50/p95/p99 latency за ендпоінтами, error-rate за кодами ('AUTH _ FAILED','SCOPE _ DENIED','IDEMPOTENCY _ MISMATCH'), частота ротацій, частка прострочених токенів.

WORM-журнал: видачі/відгуки токенів, зміна ключів, зміна політик.

Алерти: сплеск'AUTH _ FAILED', аномалії по гео/ASN, зростання «прострочений/відкликаний»> порогу.

11) Регіональна резидентність і сегментація

Токени/сертифікати прив'язані до регіону (EU/UK/BR/...).

У клеймах - «region», платформні шлюзи забороняють крос-регіональні виклики.

Роздільні KMS і Vault-кластери на регіон; ключі не «їздять» між регіонами.

12) Інциденти та відгук

Compromise playbook: миттєвий revoke ключів/токенів, блок мереж/ASN, закриття scope.

Kill-switch на рівні шлюзу: «no new sessions / funds».

Постмортем: «як потрапило в логи/репозиторій», «чому не спрацювала DLP/сканер секретів».

13) Чек-листи

A. для платформи

Всі write-шляхи: mTLS + OAuth2 CC (TTL ≤ 5 мин), `X-Idempotency-Key`, `X-Trace-Id`.
Вебхукі: HMAC/EdDSA + timestamp + nonce, дедуп по'event _ id'.
Кейстор: Vault/HSM/KMS, ротація і відгук, поділ per brand/region.
ОРА/політики: RBAC/ABAC, журнали змін, тести.
WORM-аудит і SLO-дашборди (latency, error, revoke/rotate).
DR/xaoc-навчання: закінчилися токени, підміна підпису, MITM без mTLS.

B. для провайдера (RGS/live/JP)

Не зберігаю секрети в коді; використовую Vault/підміну через змінні середовища.
Авто-ротація токенів; handle 401/403 з оновленням.
Підписую вебхукі/перевіряю вікна валідності і одноразовість.
Веду аудит ключових дій і реагую на Deprecation/Sunset заголовки.
Ідемпотентність на всіх write-викликах, дедуп по'Idempotency-Key'.

14) Анти-патерни (червоні прапори)

Статичні API-ключі без терміну придатності в проді.

Bearer-токени без прив'язки до каналу (немає MTLS/DPoP).

Зберігання секретів в Git/CI-лозі/конфігу фронтенда.

Загальний ключ/сертифікат для декількох брендів/регіонів.

Вебхуки без підпису і тимчасового вікна → реплеї.

Відсутність централізованого відгуку та WORM-журналу.

Відсутність ідемпотентності → дублі дебетів/кредитів.

15) Міні-шаблони політики (приклад, людиночитаєме)

Мандат'rgs→wallet'( EU, brand A):

`aud=wallet. api`, `scope=["bets:write","settlements:write"]`
`constraints: region=EU, brand=A, ip in {asn:…}, max_amount=5000 EUR, ttl=300s`
`binding: mTLS(cert_hash=sha256:…)`

Вебхук'wallet. credit. ok`:

'alg = Ed25519', вікно'± 300s','nonce'унікальний, дедуп'event _ id'24 години.

Безпечна автентифікація в iGaming - це комбінація практик: короткоживучі мандати, прив'язка до каналу (mTLS/DPoP), вузькі scope/audience, сувора ідемпотентність, Vault/HSM і WORM-аудит, регіональна сегментація і спостережуваність. Такий стек не заважає швидкості інтеграцій, але радикально знижує ризик витоків і фінансових інцидентів - гроші і дані залишаються під контролем, апгрейди проходять передбачувано, а комплаєнс виконується «з коробки».