API howpsuzlygy we bellikler

Gysgaça gysgaça

API howpsuzlygy, soragyň garaşylýan çeşmä garaşylýan nukdaýnazardan ýerine ýetirilmegini üpjün edýän autentifikasiýa, awtorizasiýa, kriptografiki gorag, anti-hyýanatçylykly we gözegçilik mehanizmleriniň jemidir. Esasy artefakt - çagyryş hukugyny subut edýän bellik (ýa-da haýyşnamanyň goly). Gowy binagärlik gysga ömürli belliklere, aç-açan gysgyçlara, iň az artykmaçlyklara, gaýtalanmalardan goramaga, rate limiting we amal amallaryna (aýlawlar, audit, hadysalar) esaslanýar.

API tassyklaýyş modelleri: haçan we näme saýlamaly

API-açar (statik syr)

B2B integrasiýalary we pes töwekgelçilikli ssenariýalar üçin aňsat. Konteksti götermeýär, hyzmat tarapynda saklamagy talap edýär.
Diňe IP/ASN allow-list, kesgitlenen kwotalar, gysga TTL we rotasiýalar bilen ulanyň.

OAuth 2. 1 / OIDC

Ulanyjy we hyzmatdaş integrasiýalary üçin standart: access token (gysga ömürli) + refresh token (aýlaw) + satyn almak.
Public-müşderiler - PKCE bilen; confidential-müşderiler - müşderi syry/mTLS bilen.

Client Credentials (m2m)

Maşyn → maşyn: berk kesgitlenen satyn alyşlar we audience boýunça hyzmatlar üçin access token, köplenç refresh bolmazdan (gaýtadan almak).

mTLS (özara TLS)

Şahsyýeti kanala baglaýar. Ýokary töwekgelçilikli ýa-da töleg integrasiýalary üçin amatly (TLS-iň üstündäki PoP).
OAuth bilen birleşdirilip bilner (diňe mTLS-müşderiler boýunça bellikler).

Soragyň gollary (HMAC/EdDSA)

Haçan-da transportdan garaşsyz PoP gerek bolsa: goluň ady, timestamp we nonce. Webhuklar we awtonom barlag üçin amatly.

Token formatlary we görnüşleri

JWT (JWS, gol çekilen)

Öz-özüne ýeterlik, lokal barlanýar; 'iss', 'sub', 'aud', 'exp', 'iat', 'jti', 'scope' hökmanydyr.
Töwekgelçilik - jogap bermek has kyn: gysga TTL (5-15 minut) + hadysalarda yzyna alnan 'jti' sanawyny ulanyň.

JWE (JWT kodlanan)

Payload duýgur bolsa gerek (PII). Bahasy - has ýokary çylşyrymlylyk we goşmaça çykdajylar.

Reference tokens

Aç-açan däl kesgitleýjiler Authorization Server-de introspection arkaly barlanýar - has aňsat gözden geçirmek/merkezleşdirmek.

PoP/DPoP

Belligi müşderiniň açaryna ýa-da TLS sessiýasyna birikdirmek, ogurlanan belligiň bahasyny peseldýär.

Tokeniň mazmuny: iň az ýeterlik

• 'iss' (issuer), 'sub' (subject), 'aud' (maksatly ulgam/çeşme), 'exp' (möhlet), 'iat', 'nbf' (goşmaça), 'jti'.
• 'scope '/' permissions' (iň az zerur), 'tenant' (köptenantlar üçin), 'device _ compliant '/' amr' (autentifikasiýa usuly), 'ip '/' asn' (syýasata degişli bolsa).

• Gysga TTL access (5-15 minut), refresh - 12-48 sagat (aýlanýan aýlanyş bilen).
• Auditoriýa ('aud') - gaty anyk çeşme, ýogsam "gaýtadan ulanylýan" belgi.
• Satyn almak - hereket we obýekt (mysal üçin 'payments: withdraw. read`).
• Ölçegi - sözbaşylar we proksi üçin 2-4 KB ≤; otherwiseogsam, geýtweýler bilen baglanyşykly kynçylyklar bolup biler.

Ygtyýarlandyryş we syýasat

RBAC + ABAC: rol + kontekst (gurama, geo, töwekgelçilik, enjamyň ýagdaýy).
PEP/PDP: belligi barlamak we API/proxy (Envoy/OPA) programmadan öň karar bermek.
Deklaratiw düzgünler: Git-de saklamak, CI-de policy-tests geçmek.

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
}

Haýyşlaryň goly (HMAC) we anti-replay

Zerur bolanda: webhuklar, OAuth bolmasa integrasiýa, möhüm amallary iki gezek barlamak.

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))

• Wagt rasinkrony bilen haýyşlary ret et> ± 300 s.
• Nonce 5-15 minut saklap, gaýtalamaň (replay-kesh).
• Soragyň kanonlaşdyrylan görnüşine gol çekiň (usul, ýol, query, beden heşi).

Dempotentlik we geleşik goragy

Hasapdan çykarmak/tölemek/döretmek amallary üçin idempotency-Key: birmeňzeş açar → birmeňzeş täsir.
Açaryň ömri - ≥ wagt (adatça 24-72 sagat).
Serweriň tarapynda logika: Soragyň parametrlerini munuň üçin öň ýazylan açarlar bilen deňeşdiriň.

Brauzer we ykjam müşderiler

PKCE hökmany (public-müşderiler).
Brauzerdäki refresh-token - bolmazlygy; zerur bolsa - ROTATION + gaýtalanmaga jogap (replay-detekt).
Saklamak: session storage> local storage; has gowusy - tokenler üçin backend for frontend (BFF) jogapkärdir.
SameSite, Secure, HttpOnly для cookie; CORS - aç-açan allow-lists, sözbaşylar we usullar; preflight-kesmek howpsuz.

m2m we ýokary töwekgelçilikli integrasiýa

mTLS + OAuth2 Client Credentials we 'aud'.
Geýtweýde IP/ASN allow-list.
Möhüm amallar üçin TLS-iň üstündäki PoP/DPoP ýa-da HMAC gollary.
Gurama/müşderi/açar üçin kwotalar we rate limits.

Aýlanmak, yzyna almak we hadysalara jogap bermek

Goluň syrlaryny we açarlaryny aýlamak (JWKS): meýilnama boýunça + waka bolan ýagdaýynda mejbury.
Dual-key rollout: Täze açar jübütini öňünden çap ediň (kid2), belliklerine gol çekiň, köne (kid1) TTL gutarýança tassyklamak üçin saklaň.
Refresh-rotation: her alyş-çalyş refresh → täze belgi, köne derrew hakyky däl bolýar; gaýtalamak - eglişik signaly.
Revocation: JWT üçin - gysga möhletli yzyna alnan 'jti' sanawlary; bellikler üçin - AS-da derrew blokirlemek.
Break-glass ssenarileri: minimal hukukly we gaty TTL bolan wagtlaýyn statiki kredtler, journalurnalda ýazyň.

Rate limiting, bot-gorag we artykmaç gorag

Üç gatly çäkler: per-key/per-IP/per-gurama.
Burst + sustained: token-tank/süýşýän penjire.
Çylşyrymly barlaglar: device fingerprint, özüni alyp baryş signallary, geo/ASN anomaliýalary, CAPTCHA diňe UI üçin.
Goly/NMAS gaýtadan gözden geçirilende we başarnyksyz tassyklamak synanyşygynda gulplama/slowdown.

Logistika, metrika we SLO

Iň az loglar toplumy: 'request _ id', 'client _ id', 'sub', 'aud', 'scope', 'decision', 'reason', 'jti', 'ip', 'asn', 'latency', 'quota _ state'.

• Bellikleri tassyklamagyň üstünligi (%), p95 tassyklama wagty.
• Replay-sapmalaryň ýygylygy, Idempotency-Key dublikatlary.
• PoP/DPoP/mTLS bilen haýyşlaryň paýy.
• 'aud/scope', geçen 'exp', wagt geçişi (NTP).

• Auth/AS elýeterliligi ≥ 99. 95 %/aý; p95 introspection ≤ 50 мс.
• TTL <60 c önümde nol bellikleri (gorag metrikasy).
• 0-dan az. Günde 1% 'aud/scope' ýalňyşlygy (integrasiýa hili).

Konfigurasiýa mysallary

Envoy: JWT we audience barlagy

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;

Goluň (webhuk) sözbaşysynyň mysaly

X-Signature: t=1730803210,n=ac12...,s=base64(HMAC_SHA256(secret, "POST\n/webhook\nsha256(body)\n1730803210\nac12..."))

Eger 't' 300 c-den uly bolsa, 'n' eýýäm duşuşan bolsa ýa-da 's' urmasa, serwer ret edýär.

Maglumatlary goramak we gizlinlik

Möhürleri (esasanam PII) we ömri azaldyň.
Üçünji tarap integrasiýalary üçin duýgur bellikleri (JWE) şifrläň.
Loglarda Mask/DLP: PAN/PII bilen jisimleri logirlemäň, bellikler - diňe 'kid '/baýdaklar, syryň özi däl.

Adaty ýalňyşlyklar

Uzyn aksiýalar we "baky" refresh.
'aud '/' scope' → nyşanlary köp maksatly.
Webhook goly 'timestamp '/' nonce'.
JWT diňe programmada barlanýar, geýweýde däl (PEP).
Aýlawlaryň ýoklugy we dual-key rollout.
CORS "" we başlyklara gözegçilik etmezden çözülen howply usullar.
Bellikleri BFF-siz 'localStorage' -de saklamak.

Giriş ýol kartasy

1. API-ni hasaba almak we klassifikasiýa (jemgyýetçilik/hyzmatdaş/içerki, duýgurlyk).
2. AuthN modelini saýlamak: Ulanyjylar üçin OAuth2/OIDC, mTLS + Client Credentials/HMAC m2m üçin.
3. Bellikler: gysga TTL, berk 'aud', satyn almak, möhüm amallar üçin DPoP/PoP.
4. Geýtweýde PEP: JWT, gollar we programma çenli rate limits.
5. Anti-replay we idempotentlik: timestamp/nonce/Idempotency-Key.
6. Aýlanmalar we JWKS: dual-key, awtomatlaşdyryş we alerting.
7. Syn edilişi: metrikler/SLO, giriş magazinesurnallary, UEBA signallary.
8. Maşklar: gol açaryny yzyna almak, refresh syzmagy, kwotalary aşa ýüklemek.

iGaming/fintech üçin aýratynlyklar

Tölegler/tölegler: diňe mTLS + PoP/HMAC, berk satyn almalar ('withdraw. create '), idempotency hökmanydyr.
Hyzmatdaşlar (PSP/mazmun üpjün edijileri): per-partner açarlary/şahadatnamalary, IP/ASN allow-list, aýry-aýry kwotalar we daşbordlar.
GDPR/PCI DSS: bellikleri azaltmak, üçünji tarap belliklerinde PII gadaganlygy, duýgur çeşmelere girişi logirlemek, yzygiderli access review.
Anti-abuse: özüni alyp baryş çäkleri, geo-gözegçilik, API derejesinde bonus-hyýanatçylykdan goramak.

FAQ

JWT ýa-da reference token?
JWT - öndürijilik we özbaşdaklyk; reference - merkezleşdirilen seslenme we waka-reaksiýanyň ýönekeýligi. Köplenç gibrid: daşarky - JWT, içerki - reference.

JWE gerekmi?
Diňe PII/syrlary bar bolsa. Otherwiseogsam - iň az bellikli JWS.

API açarlarynda ýaşap bolarmy?
Hawa, ýöne diňe gysga TTL, berk kwotalar, IP-allow-list we haýyşlaryň goly bilen. Ulanyjylar üçin - OAuth/OIDC has gowudyr.

DPoP/PoP hökmanymy?
Hemişe däl. Emma ýokary töwekgelçilikli amallar üçin (tölegler, netijeler) gaty islenýär.

Jemi

API-iň ygtybarly howpsuzlygy gysga ömürli belliklere, takyk satyn almalara we diňleýjilere, goralýan kanallara (TLS/mTLS), haýyşlaryň gollaryna we çäklendirmeler we gözegçilik bilen güýçlendirilen berk anti-replay goragyna esaslanýar. Awtomatlaşdyrylan aýlawlary, dual-key rollout we geýtweýlerde syýasy gözegçiligi goşuň - API-leriňiz ýokary öndürijiligi we dolandyrylyşy saklamak bilen syzmaga, gaýtalanmalara we hyýanatçylykly peýdalanmalara çydamly bolar.