Uwierzytelnianie API: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT jest standardem dla aplikacji klienckich i integracji serwerów ze złożoną autoryzacją (scopes/roles/tenants), SSO i krótkimi tokenami TTL.
Podpisy HMAC są najlepszym wyborem dla haków internetowych i prostych połączeń partnerskich „serwer → serwer” z deterministyczną weryfikacją i silną ochroną przed powtórzeniem.
Wzmocnienie bezpieczeństwa: mTLS lub DPoP (tokeny ograniczone nadawcą), krótki TTL (5-15 min), rotacja klucza (JWKS), żetony odświeżające z rotacją/anty-reuse, ścisła walidacja 'aud/iss/exp/nbf/kid' i polityka Kod na bramie.

1) Mapa rozwiązania: co stosować gdzie

2) OAuth2/OIDC: przepływy i klientów

2. 1 Przepływy

Kod autoryzacji + PKCE (Web/Mobile) - Chroni kod autoryzacji przed przechwyceniem.
Poświadczenia klienta: serwer, serwer, bez użytkownika; scopes - minimum wymagane.
Kod urządzenia: dla urządzeń bez przeglądarki.
Odśwież token: tylko dla zaufanych klientów; obracać i umożliwiać wykrywanie ponownego użycia.

2. 2 Typy klientów

Poufne (serwery, BFF): przechowywać tajemnice; używać mTLS.
Public (SPA/mobile): tajemnica nie może być przechowywana → PKCE, DPoP, krótki TTL i ograniczone zakresy.

3) JWT: struktura, czas, weryfikacja

3. 1 Pola (roszczenia)

Obowiązkowe: "iss'," sub "," aud "," exp "," iat "," nbf "," jti "," zakres "/" zezwolenia "," najemca "(jeżeli wielopoziomowy)," dziecko ".

3. 2 Okresy życia

Token dostępu: 5-15 minut.
Odświeżyć token: dni/tygodnie, obracać się z każdej wymiany; Kiedy ponownie składamy starą, blokujemy sesję.

Skew zegara: tolerancja ≤ 60 s

3. 3 JWKS i klucze

Przechowywanie kluczy w KMS/Vault, „dziecko” jest wymagane.
Dwa aktywne klucze (walcowanie), powtarzane raz na 60-90 dni lub w incydencie.
Pamięć podręczna JWKS na bramie ≤ 5 minut, z automatyczną niepełnosprawnością.

3. 4 Weryfikacja bramy/usług

Sprawdź: podpis, „aud' (zatwierdzone służby),” iss', „exp/nbf”, wykaz zamków (cofnięcie).
Nie ufaj polom od organu bez weryfikacji podpisu; ignorować 'alg = none'.

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

4) Token wiążący do klienta: mTLS, DPoP

mTLS (certyfikaty klienta TLS): token jest wydawany i zatwierdzany tylko wtedy, gdy istnieje certyfikat klienta → token jest bezużyteczny poza kombinacją certyfikatów klucza +.
DPoP (Demonstration of Proof-of-Possession): klient podpisuje każde żądanie jednorazowym kluczem → ochrona przed powtórką i kradzieżą tokena u klientów publicznych.
W przypadku tras krytycznych (mutacje płatnicze) - wymagać jednego z mechanizmów.

5) Autoryzacja: zakresy, role, ABAC

Scopes - minimalne działania („płatności: zapisz”, „płatności: status: czytaj”).
Role - jednostki dla administratorów; nie stosować ich bezpośrednio bez zakresów.
ABAC - atrybuty w tokenie ("najemca", "kraj", "kyc _ level", "risk _ flags') → zasady dotyczące bramy/OPA.
Polityka na poziomie trasy/pola (GraphQL) i na poziomie operacji domeny (REST/gRPC).

6) Podpisy HMAC: haki i partnerzy

6. 1 Pojęcie

Każda integracja ma swój własny sekret.

Podpis nad linią kanoniczną: 'timestamp + "\n' + metoda + "\n' + ścieżka + "\n' + sha256 (ciało)'

X-Signature: v1=base64(hmac_sha256(secret, canonical_string))
X-Timestamp: 2025-11-03T12:34:56Z
X-Event-Id: 01HF...

Okno czasowe: ≤ 300 sekund; Odrzucenie wniosków z wygasłym/przyszłym 'X-Timestamp'.
Idempotence: Przechowywać 'X-Event-Id' na TTL (24h) - wyrzucić duplikaty.

6. 2 Najlepsze praktyki

Sekrety w KMS/Skarbcu, obracające się co 90 dni.
Dla klientów publicznych HMAC nie jest odpowiedni (tajne przecieki); używać OAuth2/DPoP.

7) Ochrona przed powtórką, brutalną siłą i przeciekami

Nonce/„ jti ”dla operacji wrażliwych; czarną listę używanych identyfikatorów.
Stawka/kwoty: według klucza/klienta/najemcy/trasy; „drogie” operacje to odrębne kwoty.
IP/ASN/Geo zezwala na listy partnerów i haków internetowych.
Dopuszczalny typ treści („aplikacja/json”), limit wielkości ciała.
Maskowanie PII w logach; zakaz logowania żetonów/tajemnic.

8) Błędy i odpowiedzi (jednolity format)

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

• „401” - nie/nieprawidłowy token (WWW-Authenticate).
• „403” - niewystarczające prawa (zakres/ABAC).
• „429” - limity/kwoty.
• gRPC: „UNAUTHENTICATED ”/„ PERMIT _ DENIED ”/„ RESOURCE _ EXHAUSTED”.

9) Polityka okresowa i sesyjna

dostęp ≤ 15 min; Odśwież - obrót + wykrywanie ponownego użycia (złożone stare - przypomnienie sesji).
Webhaki HMAC: podpisy TTL ≤ 5 min; wielokrotna dostawa z wykładniczym backoff.
Odwołanie sesji/klucza → natychmiastowy wpis na listę odwołań (pamięć podręczna na bramce ≤ 1 min).

10) Obserwowalność i audyt

Korelacja przez 'trace _ id'/' span _ id'.
Metryki: wskaźnik sukcesu auth, '401/403/429', opóźnienie OIDC/JWKS, częstotliwość rotacji, odświeżanie ponownego użycia, udział ruchu DPoP/mTLS.
Dziennik audytu: „kto, kiedy, z którym 'sub/najemca/zakres' spowodował co”, kluczowe/tajne zmiany, nieudane podpisy HMAC.

11) Wbudowanie w API Gateway

Walidacja JWT (pamięć podręczna JWKS) i OPA/ABAC na bramce.
Profile mTLS dla zaufanych klientów/partnerów.
Weryfikacja haków HMAC na krawędzi (przed usługami wewnętrznymi).
Polityka stawek/kwot, wyłącznik na dostawcy OIDC (cache JWK).
Flagi funkcji: szybkie odłączenie klienta/klucza, zmiana algorytmu sygnatury.

12) Mini snajpery

Pseudo: weryfikacja JWT

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]

Pseudo: sprawdzanie haka internetowego HMAC

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)

Przykładowa polityka zakresu (idea OPA/Rego)

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

13) Playbooks incydentów

Wyciek klucza prywatnego/JWT-signer: reissue klucza, aktualizacja JWKS, natychmiastowe wyłączenie starego ('kid' → odmowa), odświeżenie niepełnosprawności, wymuszony wylogowanie.
Zastępowanie haków internetowych: rotacja tajemnic, lista IP permit-list, wzmacnianie okna „X-Timestamp”, wielokrotne dostarczanie pominiętych zdarzeń.
Powtórka/brutalna siła: włączyć DPoP/mTLS na trasach krytycznych, wąskie kwoty, tymczasowe bloki przez IP/ASN, włączyć listę bloków jti.
Przerwa OIDC: degradacja żetonów buforowanych (grace), dostawca wyłączników, powiadomienie klienta.

14) Listy kontrolne wdrażania

• OAuth2: Kod + PKCE (Web/Mobile), Poświadczenia klienta (serwer-serwer)
• TTL: dostęp ≤ 15 min, odświeżenie z wykrywaniem obrotu i ponownego użycia
• JWKS: dwa aktywne klucze, „dziecko”, pamięć podręczna ≤ 5 min
• Haki internetowe: HMAC v1, "X-Timestamp", "X-Event-Id', okno ≤ 300 sekund, idempotencja
• Nadawca ograniczony: mTLS/DPoP na trasach krytycznych
• ABAC/OPA: zakres + najemca/ryzyko w polityce bramowej
• Stawka/kwota - 429; Listy uprawnień IP/ASN dla partnerów
• Audyt i wpisy (401/403/429, odświeżenie ponownego użycia, podpisy HMAC)

• Nie loguj żetonów/tajemnic/pełnych organów kart
• Maskowanie PII; wsparcie DSAR; okres ważności kłód jest ograniczony

15) Anty-wzory

'alg = brak' lub zaufanie tokenowi bez weryfikacji podpisu/JWKS.
Długotrwałe żetony dostępu (godziny/dzień).
Jeden wspólny sekret HMAC dla wszystkich partnerów.
Haki bez znacznika czasu/idempotencji.
Odświeżyć żetony bez rotacji i bez wykrywania ponownego użycia.
Brak walidacji 'aud'/' iss' i rotacji' kid '.
Przechowywanie tajemnic w zmiennych środowiskowych bez KMS/Vault.

16) NFT/SLO (punkty orientacyjne)

Dostępność OIDC/JWKS ≥ 99. 95% (pamięć podręczna zmniejsza zależność).
Dodatek do walidacji JWT na bramce ≤ 2-5 ms p95.
Błędy uwierzytelniania ('401') ≤ 0. 5% całkowitego ruchu (z wyłączeniem botów).
Podpisane haki internetowe: udział zweryfikowanych z powodzeniem ≥ 99. 9%, średnie opóźnienie dostawy ≤ 3 s.

Podsumowanie

Łączenie mechanizmów: OAuth2/OIDC + JWT dla użytkowników i bogatych skryptów serwera, HMAC dla webhooks/prostych partnerów oraz dla operacji krytycznych - mTLS/DPoP. Zachowaj krótkie TTL, kluczowe obroty (JWKS), ścisłe zasady ABAC/OPA, chroń pętle przed powtarzaniem i wyciekami oraz zautomatyzuj wszystko na poziomie API Gateway. Tak więc uwierzytelnianie stanie się przewidywalne, skalowalne i bezpieczne - bez kompromisów dla UX i monetyzacji.