API təhlükəsizliyi və tokenlər
Qısa xülasə
API təhlükəsizliyi - autentifikasiya, avtorizasiya, kriptoqrafik müdafiə, sui-istifadə və müşahidə əleyhinə mexanizmlərin məcmusudur ki, bu da sorğunun gözlənilən mənbəyə gözlənilən kontekstdə yerinə yetirilməsini təmin edir. Əsas artefakt - çağırış hüququnu sübut edən token (və ya sorğunun imzası). Yaxşı memarlıq qısa ömürlü tokenlər, aydın skuplar, minimal imtiyazlar, təkrarlardan qorunma, rate limiting və əməliyyat prosedurlarına (rotasiyalar, audit, hadisələr) əsaslanır.
API autentifikasiya modelləri: nə vaxt və nə seçmək lazımdır
API açarı (statik gizli)
B2B inteqrasiyası və aşağı riskli ssenarilər üçün asandır. Kontekst daşımır, xidmət tərəfində saxlanılmasını tələb edir.
Yalnız IP/ASN allow-list, sabit kvotalar, qısa TTL və rotasiyalar ilə istifadə edin.
OAuth 2. 1 / OIDC
Xüsusi və tərəfdaşlıq inteqrasiyası üçün standart: access token (qısamüddətli) + refresh token (rotasiya) + skuplar.
Public-müştərilər - PKCE ilə; confidential-müştərilər - müştəri sirri/mTLS ilə.
Client Credentials (m2m)
Maşın → maşın: çox vaxt refresh (yenidən almaq) olmadan, ciddi şəkildə təyin edilmiş skupy və audience xidmətləri üçün access token.
mTLS (qarşılıqlı TLS)
Kimliyi kanala bağlayır. Yüksək riskli və ya ödəniş inteqrasiyaları (TLS üzərindən PoP) üçün idealdır.
OAuth ilə birləşə bilər (yalnız mTLS müştəriləri üçün tokenlər).
Sorğu imzaları (HMAC/EdDSA)
Nəqliyyatdan müstəqil PoP lazım olduqda: imza başlığı, timestamp və nonce. Vebhuk və oflayn yoxlama üçün əlverişlidir.
Tokenlərin formatları və növləri
JWT (JWS, imzalanmış)
Özünü təmin edən, yerli yoxlanılır; 'iss', 'sub', 'aud', 'exp', 'iat', 'jti', 'scope' tələb olunur.
Risk - geri çağırış daha çətindir: qısa TTL (5-15 dəq) + hadisələrdə geri çağırılan 'jti' siyahısından istifadə edin.
JWE (şifrəli JWT)
Payload həssasdırsa lazımdır (PII). Qiymət - daha yüksək mürəkkəblik və əlavə xərclər.
Reference tokens
Qeyri-şəffaf identifikatorlar Authorization Server-də introspection vasitəsilə yoxlanılır - daha asan baxış/mərkəzləşdirmə.
PoP/DPoP
Tokeni müştəri açarına və ya TLS sessiyasına bağlamaq oğurlanmış tokenin dəyərini azaldır.
Tokenin məzmunu: minimum kifayətdir
Tövsiyə olunan markalar (JWT):- 'iss' (issuer), 'sub' (subject), 'aud' (hədəf sistem/resurs), 'exp' (müddət), 'iat', 'nbf' (isteğe bağlı), 'jti'.
- 'scope '/' permissions' (minimal zəruri), 'tenant' (çoxtənənəlilər üçün), 'device _ compliant '/' amr' (autentifikasiya metodu), 'ip '/' asn' (siyasətə tətbiq olunarsa).
- access üçün qısa TTL (5-15 dəq), refresh - 12-48 saat (fırlanan rotasiya ilə).
- Auditoriya ('aud') - ciddi konkret resurs, əks halda token «təkrar istifadə edilə bilər».
- Skuplar - hərəkət və obyekt (məsələn, 'payments: withdraw. read`).
- Ölçü - başlıqlar və proxy üçün ≤ 2-4 KB; əks halda gateway problemləri mümkündür.
Avtorizasiya və siyasət
RBAC + ABAC: rol + kontekst (təşkilat, geo, risk, cihaz vəziyyəti).
PEP/PDP: tətbiqdən əvvəl API/proxy (Envoy/OPA) şlyuzunda tokenin yoxlanılması və qərar qəbul edilməsi.
Deklarativ qaydalar: Git saxlamaq, CI policy-tests keçmək.
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
}Sorğu imzası (HMAC) və anti-replay
Lazım olduqda: webhook, OAuth olmadan inteqrasiya, kritik əməliyyatların ikiqat yoxlanılması.
Başlıq sxemi (nümunə):
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))- Zaman rassinkronu ilə sorğuları rədd et> ± 300 s
- Nonce 5-15 dəqiqə saxlamaq və təkrar qəbul etməyin (replay-cache).
- Kanonlaşdırılmış sorğu təqdimatını imzalayın (üsul, yol, query, bədən hash).
İdempotentlik və əməliyyat qorunması
Idempotency-Key əməliyyat/ödəniş/yaradılması üçün: eyni açar → eyni effekt.
Açarın ömrü - ≥ iş vaxtı (adətən 24-72 saat).
Server tərəfində məntiq: sorğu parametrlərini bu açar üçün əvvəlcədən qeydə alınanlarla müqayisə edin.
Brauzer və mobil müştərilər
PKCE mütləq (public-müştərilər).
Browser-da refresh token - çəkinin; lazım olduqda - ROTATION + təkrar cavab (replay-detekt).
Saxlama: session storage> local storage; daha yaxşı - tokenlər üçün cavabdehdir backend for frontend (BFF).
SameSite, Secure, HttpOnly для cookie; CORS - açıq allow-lists, başlıqlar və metodlar; preflight-kassa təhlükəsiz.
m2m və yüksək riskli inteqrasiya
mTLS + OAuth2 Client Credentials və 'aud'.
Gateway IP/ASN allow-list.
Kritik əməliyyatlar üçün TLS üzərində PoP/DPoP və ya HMAC imzaları.
Təşkilat/müştəri/açar üçün kvotalar və rate limits.
Rotasiyalar, geri çəkilmələr və hadisələrə cavab
Sirlərin və imza açarlarının rotasiyası (JWKS): cədvəl üzrə + hadisə zamanı zorla.
Dual-key rollout: Yeni açar cütlüyünü əvvəlcədən dərc edin (kid2), tokenləri imzalayın, köhnə (kid1) TTL tükənənə qədər təsdiqləmək üçün saxlayın.
Refresh-rotation: hər mübadiləsi refresh → yeni token, köhnə dərhal etibarsız olur; təkrar - güzəşt siqnalı.
Revocation: JWT üçün - qısa müddətə geri çağırılmış 'jti' siyahıları; reference tokenləri üçün - AS-da dərhal kilidləmə.
Break-glass ssenariləri: minimal hüquqlar və sərt TTL ilə müvəqqəti statik kredtlər, jurnalda qeyd edin.
Rate limiting, bot-mühafizə və həddindən artıq qorunma
Üç qatlı limitlər: per-key/per-IP/per-təşkilat.
Burst + sustained: token tank/sürüşmə pəncərə.
Mürəkkəb yoxlamalar: device fingerprint, davranış siqnalları, geo/ASN anomaliyalar, CAPTCHA yalnız UI üçün.
Lockout/slowdown imza/NMAS yenidən və uğursuz autentifikasiya cəhdləri zamanı.
Log, Metrik və SLO
Minimum log dəsti: 'request _ id', 'client _ id', 'sub', 'aud', 'scope', 'decision', 'reason', 'jti', 'ip', 'asn', 'latency', 'quota _ state'.
Metriklər:- Tokenlərin validasiya müvəffəqiyyəti (%), p95 yoxlama vaxtı.
- Replay-sapmaların tezliyi, Idempotency-Key dublikatları.
- PoP/DPoP/mTLS ilə sorğuların payı.
- 'aud/scope', bitmiş 'exp', zaman keçidi (NTP) səhvləri.
- Auth/AS ≥ 99. 95 %/ay; p95 introspection ≤ 50 мс.
- TTL <60 c olan sıfır tokenlər (təhlükəsizlik metrikası).
- 0-dən az. Gündə 1% 'aud/scope' səhvləri (inteqrasiya keyfiyyəti).
Konfiqurasiya nümunələri
Envoy: JWT və audience yoxlama
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;İmza başlığı nümunəsi (vebhuk)
X-Signature: t=1730803210,n=ac12...,s=base64(HMAC_SHA256(secret, "POST\n/webhook\nsha256(body)\n1730803210\nac12..."))Server 't' 300 c-dən yuxarı olarsa, 'n' artıq görüşüb və ya 's 'döyülmür.
Məlumatların qorunması və məxfiliyi
Markaları (xüsusilə PII) və ömrü minimuma endirin.
Üçüncü tərəf inteqrasiyaları üçün həssas markaları (JWE) şifrələyin.
Mask/DLP log: PAN/PII ilə cəsədləri loqo etməyin, tokenlər - yalnız 'kid '/bayraqlar, özü sirr deyil.
Tipik səhvlər
Uzun sürən access-tokenlər və «əbədi» refresh.
'aud '/' scope' → tokenləri çox məqsədli deyil.
'timestamp '/' nonce' olmadan webhook imzası.
JWT-nin yalnız proqramda yoxlanılması, Gateway-də deyil (PEP).
Rotasiya və dual-key rollout yoxdur.
CORS «» və başlıqlara nəzarət etmədən həll edilmiş təhlükəli üsullar.
BFF olmadan 'localStorage' tokenlərinin saxlanması.
Yol xəritəsi
1. API inventarizasiyası və təsnifatı (ictimai/tərəfdaş/daxili, həssaslıq).
2. AuthN model seçimi: xüsusi üçün OAuth2/OIDC, mTLS + Client Credentials/m2m üçün HMAC.
3. Tokenlər: qısa TTL, sərt 'aud', cimri, kritik əməliyyatlar üçün DPoP/PoP.
4. Gateway üzərində PEP: JWT, imzalar və rate limits tətbiqinə qədər validasiya.
5. Anti-replay və idempotentlik: timestamp/nonce/Idempotency-Key.
6. Rotasiya və JWKS: dual-key, avtomatlaşdırma və alertinq.
7. Müşahidə: metriklər/SLO, giriş jurnalları, UEBA siqnalları.
8. Təlimlər: imza açarının geri çəkilməsi, refresh sızması, kvotaların həddindən artıq yüklənməsi.
iGaming/Fintech üçün xüsusiyyətlər
Ödənişlər/ödənişlər: yalnız mTLS + PoP/HMAC, ciddi alış-veriş ('withdraw. create '), idempotency tələb olunur.
Partnyorlar (PSP/məzmun provayderləri): per-partner açarları/sertifikatları, IP/ASN allow-list, ayrı-ayrı kvotalar və dashbordlar.
GDPR/PCI DSS: markaların minimuma endirilməsi, üçüncü tərəf tokenlərində PII qadağası, həssas resurslara girişin loqosu, müntəzəm access review.
Anti-abuse: davranış limitləri, geo-nəzarət, API səviyyəsində bonus istismarından qorunma.
FAQ
JWT və ya reference token?
JWT - performans və muxtariyyət; reference - mərkəzləşdirilmiş rəy və insident reaksiyasının sadəliyi. Tez-tez hibrid: xarici - JWT, daxili - reference.
JWE lazımdır?
Yalnız payload PII/sirləri var. Əks halda - minimal markalarla JWS.
API açarlarında yaşaya bilərəmmi?
Bəli, ancaq qısa TTL, sərt kvotalar, IP-allow-list və sorğu imzası ilə. İstifadəçilər üçün - daha çox OAuth/OIDC.
DPoP/PoP lazımdır?
Həmişə deyil. Lakin yüksək riskli əməliyyatlar (ödənişlər, nəticələr) üçün - son dərəcə arzuolunandır.
Yekun
API-nin etibarlı təhlükəsizliyi qısamüddətli tokenlərə, dəqiq alış-veriş və auditoriyaya, qorunan kanallara (TLS/mTLS), sorğu imzalarına və ciddi anti-replay qorunmasına əsaslanır. Avtomatik rotasiyalar, dual-key rollout və gateway siyasi nəzarət əlavə edin - və sizin API yüksək performans və idarəolunma saxlayaraq sızma, təkrarlama və sui-istifadəyə davamlı olacaq.