API аутентификациясы: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT - күрделі авторизациялы (scopes/roles/tenants), SSO және қысқа TTL токендері бар клиенттік қосымшалар мен серверлік интеграциялар үшін стандарт.
HMAC қолтаңбалары - веб-хаттар мен қарапайым серіктестік қоңыраулар үшін ең жақсы таңдау «сервер → сервер».
Қауіпсіздікті күшейтіңіз: 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: сервері, пайдаланушысы жоқ сервер; 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 полистері, OIDC-провайдерге circuit-breaker (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 және монетизация үшін ымыраға келмейтін, болжамды, масштабталатын және қауіпсіз болады.