API güvenliği ve belirteçleri

Kısa Özet

API güvenliği, bir isteğin beklenen bir varlığı beklenen bir kaynağa beklenen bir bağlamda yürütmesini sağlayan bir kimlik doğrulama, yetkilendirme, kriptografik koruma, kötüye kullanım önleme ve gözlemlenebilirlik mekanizmaları koleksiyonudur. Anahtar eser, arama hakkını kanıtlayan bir belirteçtir (veya imza talep eder). İyi bir mimari, kısa ömürlü belirteçlere, açık kapsamlara, minimum ayrıcalıklara, yeniden oynatma korumasına, hız sınırlamasına ve operasyonel prosedürlere (rotasyonlar, denetimler, olaylar) dayanır.

API Kimlik Doğrulama Modelleri - Ne Zaman ve Ne Seçilmeli

API anahtarı (statik gizli)

B2B entegrasyonları ve düşük riskli senaryolar için basittir. Bağlam taşımaz, servis tarafında depolama gerektirir.
Sadece IP/ASN izin listesi, sabit kotalar, kısa TTL ve rotasyonlarla kullanın.

OAuth 2. 1/OIDC

Kullanıcı ve ortak entegrasyonları için standart: erişim belirteci (kısa süreli) + yenileme belirteci (rotasyon) + kapsamları.
Kamu müşterileri - PKCE ile; Gizli müşteriler - istemci sırrı/mTLS ile.

Müşteri Kimlik Bilgileri (m2m)

Mashina - mashina: Kesin olarak tanımlanmış kapsamlar ve kitle üzerindeki hizmetler için erişim belirteci, genellikle yenileme olmadan (tekrar alın).

mTLS (karşılıklı TLS)

Kimliği kanala bağlar. Yüksek riskli veya ödeme entegrasyonu için idealdir (TLS üzerinden PoP).
OAuth ile birleştirilebilir (yalnızca mTLS istemcileri için belirteçler).

İstek İmzaları (HMAC/EdDSA)

Aktarımdan bağımsız bir PoP'ye ihtiyacınız olduğunda: imza başlığı, zaman damgası ve nonce. Webhooks ve çevrimdışı doğrulama için uygundur.

Token formatları ve türleri

JWT (JWS, imzalı)

Kendi kendine yeterli, yerel olarak kontrol edilir; Zorunlu 'iss', 'sub', 'aud', 'exp', 'iat', 'jti', 'scope'.
Risk - hatırlama daha zor: Olaylarda kısa TTL (5-15 dk) + geri çağrılan 'jti' listesi kullanın.

JWE (şifreli JWT)

Yük duyarlı ise gereklidir (PII). Maliyet - daha yüksek karmaşıklık ve genel gider.

Referans belirteçleri

Opak tanımlayıcılar, Authorization Server tarafından iç gözlem yoluyla kontrol edilir - daha kolay hatırlama/merkezileştirme.

PoP/DPoP

Bir belirtecin bir istemci anahtarına veya bir TLS oturumuna bağlanması, çalınan belirtecin değerini azaltır.

Token İçeriği: Minimum Yeterli

• 'iss' (ihraççı), 'sub' (konu), 'aud' (hedef sistem/kaynak), 'exp' (terim), 'iat', 'nbf' (isteğe bağlı), 'jti'.
• 'scope'/' permissions' (minimum gerekli), 'tenant' (çoklu kiracı için), 'device _ compliant'/' amr' (kimlik doğrulama yöntemi), 'ip'/' asn' (ilkeye uygunsa).

• Erişim için kısa TTL (5-15 dakika), yenileme - 12-48 saat (döner rotasyonlu).
• İzleyici ('aud') kesinlikle spesifik bir kaynaktır, aksi takdirde belirteç "yeniden kullanılabilir'dir.
• Kapsamlar - eylem ve nesne (örneğin, 'ödemeler: çekilme. Oku ').
• Boyut - Başlıklar ve proxy'ler için ≤ 2-4 KB; Aksi takdirde ağ geçitleri ile ilgili sorunlar olabilir.

Yetkilendirme ve Politikalar

RBAC + ABAC: rol + bağlam (organizasyon, coğrafi, risk, cihaz durumu).
Uygulama öncesinde API Gateway/Proxy (Envoy/OPA) üzerinde PEP/PDP Token Doğrulama ve Karar.
Bildirimsel kurallar: Git'te mağaza, CI'da politika testlerini geçin.

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
}

İstek İmzalama (HMAC) ve anti-replay

Gerektiğinde: webhooks, OAuth olmadan entegrasyon, kritik işlemleri iki kez kontrol etme.

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 yanlış hizalama> ± 300 s ile istekleri reddedin.
• Nonce 5-15 dakika saklayın ve tekrarları kabul etmeyin (yeniden oynatma önbelleği).
• Kanonlaştırılmış bir sorgu görünümü imzalayın (yöntem, yol, sorgu, gövde karma).

Kimlik ve işlem koruması

Yazma/ödeme/oluşturma işlemleri için Idempotency-Key: aynı anahtar - aynı etki.
Anahtar kullanım ömrü, ≥ iş zaman aşımı süresidir (genellikle 24-72 saat).
Sunucu tarafı mantığı - Sorgu parametrelerini daha önce bu anahtar için taahhüt edilenlerle karşılaştırın.

Tarayıcı ve mobil istemciler

PKCE zorunludur (kamu müşterileri).
Tarayıcıdaki belirteci yenileyin - kaçının; Gerekirse - ROTATION + replay response (replay-detection).
Depolama: oturum depolama> yerel depolama; Daha iyisi - ön uç için arka uç (BFF) belirteçlerden sorumludur.
SameSite, Secure, HttpOnly для çerez; CORS - açık izin listeleri, başlıklar ve yöntemler; Ön kontrol önbelleğe alma güvenli.

m2m ve yüksek riskli entegrasyonlar

mTLS + İstemci Kimlik Bilgilerini kapsamlar ve 'aud'ile OAuth2.
Ağ geçidinde IP/ASN izin listesi.
Kritik işlemler için TLS üzerinden PoP/DPoP veya HMAC imzaları.
Kuruluş/müşteri/anahtar başına kotalar ve oran sınırları.

Dönüşler, geri çağırmalar ve olay yanıtı

Gizli ve imza anahtar rotasyonu (JWKS): Olay üzerine zamanlanmış + zorlanmış.
Çift anahtarlı sunum: Önceden yeni bir anahtar çifti yayınlayın (kid2), bunun için belirteçleri imzalayın, TTL tükenene kadar eski olanı (kid1) doğrulama için saklayın.
Yenileme-rotasyon: her yenileme değişimi - yeni bir belirteç, eski hemen geçersiz hale gelir; Tekrar et - uzlaşma sinyali.
İptal: JWT için - kısa bir süre için geri çağrılan 'jti' listeleri; Referans belirteçleri için - AS'de anında engelleme.
Cam kırma komut dosyaları: minimum haklara sahip geçici statik krediler ve sert TTL, günlüğe kaydedin.

Hız sınırlaması, bot koruması ve kaba kuvvet koruması

Üç katmanlı sınırlar: anahtar başına/IP başına/kuruluş başına.
Burst + sustained: token-tank/sürgülü pencere.
Karmaşık kontroller: cihaz parmak izi, davranışsal sinyaller, coğrafi/ASN anomalileri, yalnızca UI için CAPTCHA.
İmza/NMAC ve kimlik doğrulama girişimlerini yeniden müzakere ederken kilitleme/yavaşlama başarısız olur.

Günlük kaydı, metrikler ve SLO

Minimum günlük kümesi: 'request _ id', 'client _ id', 'sub', 'aud', 'scope', 'decision', 'reason', 'jti', 'ip', 'asn', 'latency', 'cota _ state'.

• Token doğrulama başarısı (%), p95 doğrulama zamanı.
• Tekrarlama sapmalarının sıklığı, Idempotency-Key'in kopyaları.
• PoP/DPoP/mTLS ile isteklerin yüzdesi.
• 'aud/scope' errors, süresi dolmuş 'exp', zaman kaymaları (NTP).

• Auth/AS ≥ 99 kullanılabilirliği. %95/ay; P95 iç gözlem ≤ 50 мс.
• Prod'da TTL <60 s ile sıfır belirteçler (guard metrik).
• 0'dan küçük. Günde %1 'aud/scope' errors (entegrasyonların kalitesi).

Yapılandırma örnekleri

Elçi: JWT ve seyirci kontrolü

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 к arka uç

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ığı örneği (webhooks)

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

Eğer't '300 c'den büyükse,'n' zaten karşılaşmışsa veya's 'yenilmezse sunucu reddeder.

Veri koruma ve gizlilik

Ayırt edici özellikleri (özellikle PII) ve yaşam sürelerini en aza indirin.
Üçüncü taraf entegrasyonları için hassas damgaları (JWE) şifreleyin.
Günlüklerde Maske/DLP: gövdeleri PAN/PII, belirteçlerle kaydetmeyin - sadece'çocuk "/bayraklar, sırrın kendisi değil.

Yaygın hatalar

Uzun ömürlü erişim belirteçleri ve "ebedi" yenileme.
'Aud'/' scope' yokluğu - belirteçler çok amaçlıdır.
'Zaman damgası'/' nonce' olmadan webhook'ların imzası.
JWT'yi yalnızca uygulamada kontrol edin, ağ geçidinde (PEP) değil.
Döndürme ve çift anahtarlı kullanıma sunma yok.
"CORS've başlık kontrolü olmadan güvensiz yöntemlere izin verdi.
Belirteçleri BFF olmadan 'yerel Depolama'da saklamak.

Uygulama Yol Haritası

1. API envanteri ve sınıflandırması (public/partner/internal, sensitivity).
2. AuthN model seçimi: Özel için OAuth2/OIDC, mTLS + İstemci Kimlik Bilgileri/m2m için HMAC.
3. Belirteçler: kısa TTL, sıkı 'aud', kapsamlar, kritik işlemler için DPoP/PoP.
4. Ağ geçitlerinde PEP: JWT doğrulama, imzalar ve uygulamaya oran sınırları.
5. Anti-replay ve idempotency: zaman damgası/nonce/Idempotency-Key.
6. Rotasyonlar ve JWKS: çift anahtar, otomasyon ve uyarı.
7. Gözlemlenebilirlik: metrikler/SLO, erişim günlükleri, UEBA sinyalleri.
8. Egzersizler: imza anahtarı, yenileme sızıntısı, kota aşırı yüklenmesi.

İGaming/fintech için Özgüllük

Ödemeler/ödemeler: Yalnızca mTLS + PoP/HMAC, sıkı kapsamlar ('çekilme. create '), idempotency gereklidir.
Ortaklar (PSP/içerik sağlayıcıları): Ortak başına anahtarlar/sertifikalar, IP/ASN izin listesi, bireysel kotalar ve panolar.
GDPR/PCI DSS: damgaları en aza indirmek, üçüncü taraf belirteçlerde PII'yi yasaklamak, hassas kaynaklara erişimi günlüğe kaydetmek, düzenli erişim incelemesi.
Kötüye kullanımı önleme: davranışsal sınırlar, coğrafi kontrol, API düzeyinde bonus kötüye kullanımına karşı koruma.

SSS

JWT veya referans belirteç?
JWT - performans ve özerklik; Referans - merkezi geri bildirim ve olay yanıtının basitliği. Genellikle bir melez: harici - JWT, dahili - referans.

JWE gerekli mi?
Yalnızca yük PII/sırlar içeriyorsa. Aksi takdirde - Minimum işaretlerle JWS.

API anahtarlarıyla yaşayabilir miyim?
Evet, ama sadece kısa TTL, sıkı kotalar, IP-allow-list ve istek imzalama ile. Kullanıcılar için OAuth/OIDC tercih edilir.

DPoP/PoP zorunlu mu?
Her zaman değil. Ancak yüksek riskli operasyonlar için (ödemeler, sonuçlar) oldukça arzu edilir.

Toplam

Güvenilir API güvenliği, kısa ömürlü belirteçler, doğru kapsamlar ve kitleler, güvenli kanallar (TLS/mTLS), istek imzalama ve katı yeniden oynatma önleme koruması, sınırlar ve gözlemlenebilirlik ile geliştirilmiştir. Ağ geçitlerine otomatik döndürme, çift anahtarlı kullanıma sunma ve siyasi kontrol ekleyin; API'niz yüksek performans ve yönetilebilirliği korurken sızıntılara, tekrarlara ve kötüye kullanıma karşı dayanıklı olacaktır.