Bezpieczeństwo i żetony API

Krótkie podsumowanie

Zabezpieczenie API jest zbiorem mechanizmów uwierzytelniania, autoryzacji, ochrony kryptograficznej, przeciwdziałania nadużyciom i obserwowalności, które gwarantują, że żądanie wykonuje oczekiwany podmiot do oczekiwanego zasobu w oczekiwanym kontekście. Kluczowym artefaktem jest token (lub podpis żądania) potwierdzający prawo do wywołania. Dobra architektura opiera się na krótkotrwałych żetonach, jasnych zakresach, minimalnych uprawnieniach, ochronie przed powtórzeniami, ograniczeniu tempa i procedurach operacyjnych (rotacje, audyty, incydenty).

Modele uwierzytelniania API - kiedy i co wybrać

Klucz API (tajemnica statyczna)

Proste dla integracji B2B i scenariuszy niskiego ryzyka. Nie zawiera kontekstu, wymaga przechowywania po stronie serwisowej.
Stosować tylko z listą zezwoleń IP/ASN, kwotami stałymi, krótkim TTL i obrotami.

OAuth 2. 1/OIDC

Standard dla integracji użytkownika i partnera: token dostępu (krótkoterminowy) + token odświeżający (obrót) + zakresy.
Klienci publiczni - z PKCE; klienci poufni - z tajemnicą klienta/mTLS.

Poświadczenia klienta (m2m)

Mashina → mashina: token dostępu do usług na ściśle określonych zakresach i publiczności, często bez odświeżania (ponownie).

mTLS (mutual TLS)

Łączy tożsamość z kanałem. Idealny do integracji wysokiego ryzyka lub płatności (PoP nad TLS).
Można łączyć z OAuth (żetony tylko dla klientów mTLS).

Podpisy pod wnioskiem (HMAC/EdDSA)

Kiedy potrzebujesz niezależnego od transportu PoP: nagłówek podpisu, znacznik czasu i nonce. Wygodne dla webhooks i weryfikacji offline.

Formaty i typy tokenów

JWT (JWS, podpisane)

Samowystarczalny, sprawdzany lokalnie; obowiązkowe 'iss',' sub ',' aud', 'exp', 'iat', 'jti', 'scope'.
Ryzyko - przypominać trudniejsze: użyć krótkiego TTL (5-15 min) + listę przypominanych „jti” w incydentach.

JWE (zaszyfrowana JWT)

Potrzebne, jeśli ładunek jest wrażliwy (PII). Koszt - większa złożoność i koszty ogólne.

Żetony referencyjne

Nieprzezroczyste identyfikatory, sprawdzane przez introspekcję przez serwer autoryzacji - łatwiejsze odzyskiwanie/centralizacja.

PoP/DPoP

Powiązanie tokena z kluczem klienta lub z sesją TLS zmniejsza wartość skradzionego tokena.

Zawartość tokenu: Minimum wystarczające

Zalecane znaczki (JWT):

„iss' (emitent),” sub „(przedmiot),” aud' (system docelowy/zasoby), „exp” (termin), „iat”, „nbf” (opcjonalnie), „jti”.
"scope "/" permissions" (minimum wymagane), "najemca" (dla wielu najemców), "device _ compliant "/" amr" (metoda uwierzytelniania), "ip "/" asn' (jeżeli dotyczy polityki).

Zasady:

Krótki TTL dla dostępu (5-15 min), odświeżyć - 12-48 h (z rotacją).
Publiczność ('aud') jest ściśle określonym zasobem, w przeciwnym razie token jest „wielokrotnego użytku”.
Scopes - akcja i obiekt (na przykład "płatności: wypłacić. odczytać ").
Rozmiar - ≤ 2-4 KB dla nagłówków i proxy; w przeciwnym razie mogą wystąpić problemy z bramami.

Autoryzacja i zasady

RBAC + ABAC: rola + kontekst (organizacja, geo, ryzyko, stan urządzenia).
PEP/PDP Token Validation and Decision on API Gateway/Proxy (Envoy/OPA) przed złożeniem wniosku.
Zasady deklaracyjne: przechowywać w Git, przejść testy polityki w CI.

Przykład Rego (uproszczony):

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
}

Żądanie podpisania (HMAC) i anty-replay

W razie potrzeby: haki internetowe, integracja bez OAuth, podwójne sprawdzanie krytycznych operacji.

Schemat nagłówka (przykład):


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

Zasady:

Odrzuć żądania z błędnym określeniem czasu> ± 300 s.
Nonce przechowywać przez 5-15 minut i nie akceptować powtórki (powtórka cache).
Podpisz kanonizowany widok zapytania (metoda, ścieżka, zapytanie, hash ciała).

Ochrona tożsamości i transakcji

Idempotency-Key do umorzenia/wypłaty/tworzenia operacji: ten sam klucz → ten sam efekt.
Kluczowym okresem życia jest ≥ czas pracy (zwykle 24-72 godziny).
Logika po stronie serwera - Porównaj parametry zapytania z parametrami uprzednio popełnionymi dla tego klucza.

Przeglądarka i klienci mobilni

PKCE jest obowiązkowa (klienci publiczni).
Odśwież token w przeglądarce - unikaj; w razie potrzeby - ROTATION + replay response (replay-detection).
Przechowywanie: pamięć sesyjna> pamięć lokalna; lepiej - backend for frontend (BFF) odpowiada za żetony.
• Witryna, Bezpieczne, Tylko дла cookie; CORS - wyraźne listy zezwoleń, nagłówki i metody; preflight buforowanie jest bezpieczne.

m2m i integracje wysokiego ryzyka

mTLS + OAuth2 Poświadczenia klienta z zakresami i 'aud'.
Lista uprawnień IP/ASN na bramce.
Podpisy PoP/DPoP lub HMAC nad TLS dla operacji krytycznych.
Limity kwot i stawek na organizację/klienta/klucz.

Rotacje, wycofania i reakcja na incydenty

Rotacja klucza tajnego i podpisu (JWKS): zaplanowana + egzekwowana w przypadku incydentu.
Podwójny klucz rollout: opublikować nową parę kluczy z wyprzedzeniem (kid2), podpisać żetony dla niego, zachować starą (kid1) do walidacji do czasu wyczerpania TTL.
Odświeżanie-rotacja: każda wymiana odświeżania → nowy token, stary natychmiast staje się nieprawidłowy; powtarzać - sygnał kompromisowy.
Cofnięcie: w przypadku JWT - listy przywołanych „jti” na krótki czas; dla żetonów referencyjnych - natychmiastowe blokowanie na AS.
Skrypty break-glass: tymczasowe kredyty statyczne z minimalnymi prawami i twardym TTL, zapis w dzienniku.

Ograniczenie tempa, ochrona przed botem i ochrona przed brutalną siłą

Granice trzech warstw: per-key/per-IP/per-organization.
Wybuch + trwały: token-zbiornik/przesuwne okno.
Skomplikowane kontrole: odcisk palca urządzenia, sygnały behawioralne, anomalie geo/ASN, CAPTCHA tylko dla interfejsu użytkownika.
Blokada/spowolnienie podczas renegocjowania podpisu/NMAC i próby uwierzytelniania nie powiodły się.

Rejestrowanie, mierniki i SLO

Minimalny zestaw kłód: 'request _ id',' client _ id', 'sub', 'aud',' scope ',' decision ',' reason ',' jti ',' ip ',' asn', 'latency', 'quota _ state'.

Metryka:

Sukces walidacji tokenu (%), czas weryfikacji p95.
Częstotliwość odchyleń powtórnych, duplikaty Idempotence-Key.
Odsetek wniosków z PoP/DPoP/mTLS.
'aud/scope' błędy, wygasły 'exp', przesunięcia czasu (NTP).

SLO (przykłady):

Dostępność Auth/AS ≥ 99. 95 %/miesiąc; p95 introspekcja ≤ 50 со.
Zero żetonów z TTL <60 s w prod (guard metric).
Mniej niż 0. 1% błędów 'aud/scope' dziennie (jakość integracji).

Przykłady konfiguracji

Wysłannik: JWT i kontrola publiczności

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;

Przykład nagłówka podpisu (haki internetowe)


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

Serwer odrzuca, jeśli 't' jest starszy niż 300 c, 'n' już spełnił lub' nie bije.

Ochrona danych i prywatność

Zminimalizować cechy charakterystyczne (zwłaszcza PII) i okresy życia.
Szyfruj znaczki wrażliwe (JWEs) dla integracji osób trzecich.
Maska/DLP w dziennikach: nie loguj ciał z PAN/PII, żetony - tylko 'kid '/flagi, a nie sam sekret.

Częste błędy

Długotrwałe żetony dostępu i „wieczne” odświeżenie.
Brak 'aud '/' scope' → tokeny są wielofunkcyjne.
Podpis haków internetowych bez „znacznika czasu ”/„ nonce”.
Sprawdzanie JWT tylko w aplikacji, a nie w bramce (PEP).
Żadnych obrotów i podwójnego klucza.
„CORS” i dozwolone metody niepewności bez sterowania nagłówkiem.
Przechowywanie tokenów w magazynie bez BFF.

Plan realizacji

1. Inwentaryzacja i klasyfikacja API (publiczna/partnerska/wewnętrzna, wrażliwość).
2. Wybór modelu AuthN: OAuth2/OIDC dla niestandardowych, mTLS + Uwierzytelnienia klienta/HMAC dla m2m.
3. Tokeny: krótki TTL, ścisły 'aud', zakresy, DPoP/PoP dla operacji krytycznych.
4. PEP na bramach: walidacja JWT, podpisy i limity stawek do aplikacji.
5. Anty-replay i idempotence: timestamp/nonce/Idempotence-Key.
6. Obroty i JWKS: podwójny klucz, automatyzacja i ostrzeganie.
7. Obserwowalność: mierniki/SLO, dzienniki dostępu, sygnały UEBA.
8. Ćwiczenia: klucz podpisu, odświeżenie wycieku, przeciążenie kontyngentu.

Specyfika dla iGaming/fintech

Płatności/wypłaty: tylko mTLS + PoP/HMAC, ścisłe zakresy ("wypłacić. tworzyć "), idempotencja jest wymagana.
Partnerzy (dostawcy PSP/treści): klucze/certyfikaty dla każdego partnera, lista zezwoleń IP/ASN, indywidualne kwoty i deski rozdzielcze.
GDPR/PCI DSS: minimalizacja znaczków, zakaz PII w żetonach osób trzecich, rejestrowanie dostępu do zasobów wrażliwych, regularny przegląd dostępu.
Przeciwdziałanie nadużyciom: ograniczenia behawioralne, kontrola geograficzna, ochrona przed nadużyciami bonusowymi na poziomie API.

NAJCZĘŚCIEJ ZADAWANE PYTANIA

JWT czy token referencyjny?
JWT - wydajność i autonomia; reference - scentralizowane informacje zwrotne i prostota reakcji na incydenty. Często hybryda: zewnętrzna - JWT, wewnętrzna - odniesienie.

Czy WWE jest potrzebne?
Tylko jeśli ładunek użytkowy zawiera PII/sekrety. W przeciwnym razie - JWS z minimalnymi cechami charakterystycznymi.

Czy mogę żyć na kluczykach API?
Tak, ale tylko z krótkim TTL, rygorystyczne kwoty, IP-let-list i żądanie podpisania. Dla użytkowników preferowany jest OAuth/OIDC.

DPoP/PoP obowiązkowe?
Nie zawsze. Ale w przypadku operacji wysokiego ryzyka (płatności, wnioski) jest bardzo pożądane.

Razem

Niezawodne bezpieczeństwo API jest zbudowane na krótkotrwałych żetonach, dokładnych zakresach i odbiorcach, bezpiecznych kanałach (TLS/mTLS), podpisywaniu żądań i ścisłej ochronie przed powtórzeniem, wzmocnionej limitami i obserwowalnością. Dodaj zautomatyzowane obroty, podwójne klucze i kontrolę polityczną na bramach - a Twój interfejs API będzie odporny na wycieki, powtórki i nadużycia, przy zachowaniu wysokiej wydajności i możliwości zarządzania.