API-ni tassyklamak: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT - çylşyrymly ygtyýarnamasy (skopes/roles/tenants), SSO we gysga TTL bellikleri bolan müşderi programmalary we serwer integrasiýalary üçin standart.
HMAC gollary - kesgitlenen barlag we replay-den berk goragy bolan "serwer → serwer" webhuklary we ýönekeý hyzmatdaş jaňlar üçin iň gowy saýlama.
Howpsuzlygy güýçlendiriň: mTLS ýa-da DPoP (sender-constrained tokens), gysga TTL (5-15 min), açar aýlanyşy (JWKS), aýlanmaga garşy refress-tokenler/anti-reuse, berk tassyklama 'aud/iss/exp/nbf/kid' we gateway-da policy-as-code.

1) Çözgütleriň kartasy: nirede ulanmaly

2) OAuth2/OIDC: akymlar we müşderiler

2. 1 Akymlar

Authorization Code + PKCE (Web/Mobile): ygtyýar koduny tutmakdan goraýar.
Client Credentials: Ulanyjy ýok serwer; skopes - iň az zerur.
Device Code: brauzersiz enjamlar üçin.
Refresh Token: diňe ynamdar müşderiler üçin; reuse detection-i aýlanyň we açyň.

2. 2 Müşderi görnüşleri

Confidential (serwerler, BFF): syrlary saklaýarlar; mTLS ulanyň.
Public (SPA/mobile): gizlin saklanyp bilinmez → PKCE, DPoP, gysga TTL we çäkli skopes.

3) JWT: gurluşy, möhleti, barlagy

3. 1 Meýdanlar (claims)

Hökmany: 'iss', 'sub', 'aud', 'exp', 'iat', 'nbf', 'jti', 'scope '/' permissions', 'tenant', 'kid'.

3. 2 Durmuş şertleri

Access token: 5-15 minut.
Refresh token: günler/hepdeler, her alyş-çalşykda aýlanýarys; köne tabşyrylanda - sessiýany petikleýäris.
Clock skew: rugsat ≤ 60 sek.

3. 3 JWKS we açarlar

Açarlary KMS/Vault, 'kid' -de saklamak hökmanydyr.
Iki sany işjeň açar (rolling), 60-90 günde bir gezek ýa-da hadysada gaýtadan goýberilýär.
JWKS gateway keşi ≤ 5 minut, awto-maýyplyk bilen.

3. 4 Gateway/hyzmatlarda barlamak

Barlaň: gol, 'aud' (rugsat edilen hyzmatlar), 'iss', 'exp/nbf', blokirlemeleriň sanawy (revocation).
Goly barlamazdan beden meýdanlaryna ynanmaň; 'alg = none' -a üns bermäň.

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

4) Belligi müşderi bilen baglanyşdyrmak: mTLS, DPoP

mTLS (TLS müşderi şahadatnamalary): belgi diňe müşderi şahadatnamasy bolan ýagdaýynda berilýär we tassyklanýar → belgi "açar + şahadatnama" baglanyşygynyň daşynda peýdasyz.
DPoP (Demonstration of Proof-of-Possession): müşderi her haýyşa bir gezeklik açar bilen gol çekýär → köpçüligiň müşderilerinde tokeniň repleýinden we ogurlanmagyndan goramak.
Möhüm ugurlar üçin (töleg mutasiýalary) - mehanizmleriň birini talap etmek.

5) Ygtyýarnama: skopes, roles, ABAC

Scopes - iň az hereket ('payments: write', 'payouts: status: read').
Roles - administratorlar üçin agregatlar; skopes bolmasa olary gönüden-göni ulanmaň.
ABAC - tokendäki atributlar ('tenant', 'country', 'kyc _ level', 'risk _ flags') → gateway/OPA syýasatlary.
Ugur/meýdan derejesinde (GraphQL) we domen amallary derejesinde (REST/gRPC) syýasat.

6) HMAC-gollar: webhuklar we hyzmatdaşlar

6. 1 Konsepsiýa

Her integrasiýanyň öz syry bar.

Kanoniki setiriň üstündäki gol: '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...

Wagt penjiresi: ≤ 300 sek; möhleti geçen/geljekki 'X-Timestamp' haýyşlary ret edilsin.
Idempotentlik: 'X-Event-Id' -ni TTL-de saklaň (24 sagat) - dublikatlary taşlaň.

6. 2 Iň oňat tejribe

KMS/Vault-da syrlar, her 90 günde aýlanmak.
Köpçülige açyk müşderiler üçin HMAC laýyk gelmeýär (syr syzýar); OAuth2/DPoP ulanyň.

7) Replay, brute force we syzmakdan goramak

Nonce/' jti 'duýgur amallar üçin; ulanylan kesgitleýjileriň gara sanawy.
Rate/quotas: açar/müşderi/tenant/ugur boýunça; "gymmat" amallar - aýratyn kwotalar.
IP/ASN/Geo allow-lists partnýorlar we webhuklar üçin.
Content-type allow ('application/json'), beden ululygynyň çägi.
PII-ni ýazgylarda gizlemek; bellikleri/syrlary ýazmagy gadagan etmek.

8) Ýalňyşlyklar we jogaplar (ýeke-täk format)

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

• '401' - ýok/galyp däl token (WWW-Authenticate).
• '403' - ýeterlik hukuklar ýok (skope/ABAC).
• '429' - çäklendirmeler/kwotalar.
• gRPC: `UNAUTHENTICATED`/`PERMISSION_DENIED`/`RESOURCE_EXHAUSTED`.

9) Möhletleriň we sessiýalaryň syýasaty

Access ≤ 15 min; Refresh - rotasiýa + reuse detection (köne tabşyryldy - sessiýany yzyna almak).
Webhuki HMAC: TTL gollary ≤ 5 min; eksponensial backoff bilen gaýtadan eltip bermek.
Sessiýany/açary yzyna almak → derrew revocation list-a girmek (gateway-daky keş ≤ 1 minut).

10) Gözegçilik we audit

'trace _ id '/' span _ id' boýunça baglanyşyk.
Metrikler: auth success rate, '401/403/429', gizlinlik OIDC/JWKS, aýlanma ýygylygy, reuse refresh, traffigiň DPoP/mTLS paýy.
Audit-log: "kim, haçan, haýsy 'sub/tenant/skope' bilen näme", açarlaryň/syrlaryň üýtgemegi, HMAC-yň şowsuz gollary.

11) Gateway API-e goşulmak

Şlýuzda JWT-tassyklama (JWKS kesh) we OPA/ABAC.
mTLS ygtybarly müşderiler/hyzmatdaşlar üçin profiller.
HMAC-webhuklary edge-de barlamak (içerki hyzmatlara çenli).
Rate/Quota syýasatlary, OIDC-üpjün edijisinde circuit-breaker (JWK keş).
Feature-flags: Müşderi/açaryň çalt öçürilmegi, gol algoritminiň üýtgemegi.

12) Kiçi snippetler

Psevdo: JWT barlagy

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]

Psevdo: HMAC webhuk barlagy

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)

Skope-syýasatyň mysaly (OPA/Rego ideýa)

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

13) Wakalaryň pleýbuklary

Şahsy açaryň syzmagy/JWT-abonent: açarlary gaýtadan çykarmak, JWKS-i täzelemek, köne açary derrew öçürmek ('kid' → deny), refresh maýyplygy, mejbury logout.
Webhuklary çalyşmak: syrlary aýlamak, IP allow-list, 'X-Timestamp' penjiresini güýçlendirmek, sypdyrylan wakalary gaýtalamak.
Replay/brutfors: möhüm ugurlarda DPoP/mTLS-i, kwotalaryň daralmagyny, IP/ASN boýunça wagtlaýyn bloklary, 'jti' -bloklisti açyň.
Outage OIDC: kesilen tokenleriň zaýalanmagy (grace), üpjün edijiniň circuit-breaker, müşderi habarnamasy.

14) Girizmegiň çek-listleri

• OAuth2: Code+PKCE (Web/Mobile), Client Credentials (server-to-server)
• TTL: Access ≤ 15 min, Refresh we reuse detection
• JWKS: iki sany açar, 'kid', 5 minutlyk nagt ≤
• Webhuklar: HMAC v1, 'X-Timestamp', 'X-Event-Id', penjire ≤ 300 sek, idempotentlik
• Sender-constrained: Kritik ugurlarda mTLS/DPoP
• ABAC/OPA: şlýuz syýasatlarynda skopes + tenant/risk
• Rate/Quota и 429; IP/ASN allow-lists partnýorlar üçin
• Audit we alertler (401/403/429, reuse refresh, HMAC gollary)

• Nyşanlary/syrlary/kartoçkalaryň doly jisimlerini ýazga almaň
• Gizlemek PII; DSAR goldawy; ýazgylaryň saklanyş möhleti çäklidir

15) Anti-patternler

'alg = none' ýa-da JWKS goluny barlamazdan tokene ynam.
Uzak ömürli access-tokenler (sagat/gün).
Ähli hyzmatdaşlar üçin bir umumy HMAC-syr.
Taýmstampsiz/idempotentsiz webhuklar.
Refresh-tokenler rotasiýasyz we reuse detection.
'aud '/' iss' -validasiýa we 'kid' -rotasiýa ýok.
KMS/Vault bolmasa gurşaw üýtgeýjilerinde syrlary saklamak.

16) NFT/SLO (görkezmeler)

OIDC/JWKS elýeterlilik ≥ 99. 95% (edge-kesh garaşlylygy azaldar).
JWT gateway goşundysyny tassyklamak ≤ 2-5 ms p95.
Autentifikasiýa ýalňyşlyklary ('401') ≤ 0. Umumy traffigiň 5% -i (botlary hasaba almazdan).
Gol çekilen webhuklar: üstünlikli tassyklanan ≥ paýy 99. 9%, eltmegiň ortaça gijikdirilmegi ≤ 3 s.

Gysgaça maglumat

Mehanizmleri birleşdiriň: Ulanyjylar we baý serwer ssenarileri üçin OAuth2/OIDC + JWT, webhook/ýönekeý hyzmatdaşlar üçin HMAC we möhüm amallar üçin - mTLS/DPoP. Gysga TTL-leri, açar aýlawlaryny (JWKS), ABAC/OPA-nyň berk syýasatlaryny saklaň, konturlary replay we syzmakdan goraň we hemme zady Gateway API derejesinde awtomatlaşdyryň. Şeýlelik bilen, tassyklamak UX we monetizasiýa üçin ylalaşyk bolmazdan öňünden aýdyp boljak, ulaldylyp bilinjek we howpsuz bolar.