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

TL; DR

OAuth2/OIDC + JWT - татаал уруксат менен кардар колдонмолору жана Server Integration үчүн стандарт (scopes/roles/tenants), SSO жана кыска TTL токендер.
HMAC колтамгалары - бул аныкталбаган текшерүү жана катуу replay коргоо менен "сервер → сервер" вебхуктар жана жөнөкөй өнөктөш чалуулар үчүн эң жакшы тандоо.
Коопсуздукту күчөтүү: mTLS же DPoP (sender-constrained tokens), кыска TTL (5-15 мин), ачкычтарды айлантуу (JWKS), айлануу менен refresh-токендер/анти-reuse, катуу валидация 'aud/iss/exp/nbf/kid' and policy-as-code on gateway.

1) Чечим картасы: кайда колдонуу керек

2) OAuth2/OIDC: агымдар жана кардарлар

2. 1 агымдары

Authorization Code + PKCE (Web/Mobile): бөгөт кодун коргойт.
Client Credentials: Колдонуучусуз сервер, сервер; scopes - минималдуу зарыл.
Device Code: браузерсиз түзмөктөр үчүн.
Refresh Token: ишенимдүү кардарлар үчүн гана; айлануу жана reuse detection.

2. 2 Кардар түрлөрү

Confidential (Server, BFF): сырларды сактоо; mTLS колдонуу.
Public (SPA/мобилдик): жашыруун сактоого мүмкүн эмес → PKCE, DPoP, кыска TTL жана чектелген scopes.

3) JWT: түзүмү, мөөнөтү, текшерүү

3. 1 талаалар (claims)

Милдеттүү: 'iss', 'sub', 'aud', 'exp', 'iat', 'nbf', 'jti', 'scope '/' permissions', 'tenant' (көп ижара болсо), 'kid'.

3. 2 Жашоо мөөнөтү

Access токен: 5-15 мүнөт.
Refresh token: күн/жума, ар бир алмашуу учурунда айланат; кайра берүүдө - сессияны бөгөттөйбүз.
Clock skew: кабыл алуу ≤ 60 сек.

3. 3 JWKS жана ачкычтар

Ачкычтарды KMS/Vault, 'kid' сактоого милдеттүү.
Эки активдүү ачкычтар (rolling), 60-90 күн же окуя бир жолу кайра чыгаруу.
gateway боюнча JWKS кэш ≤ 5 мүнөт, auto-майыптыгы менен.

3. 4 Gateway/Services боюнча текшерүү

Салыштыруу: кол, 'aud' (уруксат берилген кызматтар), 'iss', 'exp/nbf', кулпу тизмеси (revocation).
Кол тамганы текшербестен дененин талааларына ишенбеңиз; 'alg = none' дегенге көңүл бурбаңыз.

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

4) Токенди кардарга байлоо: mTLS, DPoP

mTLS (TLS кардар күбөлүктөрү): Токен берилген жана кардар күбөлүк менен гана тастыкталат → Токен "ачкыч + күбөлүк" байламтасынан тышкары пайдасыз.
DPoP (Proof-of-Possession Demonstration): кардар бир жолку ачкычы менен ар бир өтүнүчкө кол коёт → коомдук кардарларда токенди кайталоодон жана уурдоодон коргоо.
Критикалык маршруттар үчүн (төлөм мутациялары) - механизмдердин бирин талап кылуу.

5) Authorization: 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 кол тамгалар: Webhook жана өнөктөштөр

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 күч жана агып коргоо

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 (эски берилген - сессияны карап чыгуу).
Webhuke 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-validation (JWKS кэш) жана OPA/ABAC шлюз.
Ишенимдүү кардарлар/өнөктөштөр үчүн mTLS профилдери.
edge боюнча HMAC-текшерүү (ички кызмат чейин).
Rate/Quota саясат, OIDC-провайдер боюнча circuit-breaker (JWK кэш).
Feature-flags: тез кардар/ачкыч өчүрүү, кол алгоритмин өзгөртүү.

12) Mini Сниппет

Псевдо: 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 Webhook текшерүү

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) Playbook окуялар

Жеке ачкычтын ачылышы/JWT жазылуучусу: ачкычтарды кайра чыгаруу, JWKS жаңыртуу, эскини дароо өчүрүү ('kid' → deny), майып refresh, мажбурлоо logout.
Вебхуктарды алмаштыруу: сырларды айлантуу, IP тизмеси, 'X-Timestamp' терезесин бекемдөө, өтүп кеткен окуяларды кайра жеткирүү.
Replay/brutfors: критикалык жолдор боюнча DPoP/mTLS камтыйт, квота кыскартуу, IP/ASN боюнча убактылуу блоктор, 'jti' -блокту камтыйт.
Outage OIDC: cached токендер деградациясы (grace), circuit-breaker, кардарларга эскертүү.

14) Киргизүүнүн чек-баракчалары

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

• Токендерди/сырларды/толук дене карталары логин жок
• PII жашыруу; DSAR колдоо; сактоо мөөнөтү чектелген

15) Анти-үлгүлөрү

'alg = none' же кол тамганы/JWKS текшерүүсүз токенге ишеним.
Узак мөөнөттүү access токендер (саат/күн).
Бардык өнөктөштөр үчүн бир жалпы HMAC-жашыруун.
Vebhuke тайм-штамм/idempotentity жок.
Refresh-токендер эч кандай айлануу жана reuse detection жок.
Жок 'aud '/' iss' -валидация жана 'kid' -ротация.
KMS/Vault жок чөйрө өзгөрмөлүү сырларды сактоо.

16) NFT/SLO (көрсөтмөлөр)

OIDC/JWKS жеткиликтүүлүгү ≥ 99. 95% (edge кэш көз карандылыкты азайтат).
JWT validation gateway кошумча ≤ 2-5 ms p95.
Аутентификация каталары ('401') ≤ 0. Жалпы трафиктин 5% (ботторду эсепке албаганда).
Кол коюлган вебхактар: ийгиликтүү текшерилген ≥ үлүшү 99. 9%, орточо жеткирүү кечигүү ≤ 3 с.

Резюме

Механизмдерди айкалыштыруу: OAuth2/OIDC + JWT колдонуучулар жана бай сервердик сценарийлер үчүн, HMAC вебхуктар/жөнөкөй өнөктөштөр үчүн жана критикалык операциялар үчүн - mTLS/DPoP. Кыска TTL, ачкычтарды айлантуу (JWKS), ABAC/OPA катуу саясатын сактап, контурларды кайталоодон жана агып чыгуудан коргоп, баарын API Gateway деңгээлинде автоматташтырыңыз. Ошентип, аутентификация алдын ала, масштабдуу жана коопсуз болот - UX жана акча табуу үчүн эч кандай компромисс жок.