API-Authentifizierung: OAuth2, JWT, HMAC

TL; DR

OAuth2/OIDC + JWT ist ein Standard für Clientanwendungen und Serverintegrationen mit komplexer Autorisierung (Scopes/Roles/Tenants), SSO und kurzen TTL-Token.
HMAC-Signaturen sind die beste Wahl für Webhooks und einfache server→server-Partneranrufe mit deterministischer Validierung und hartem Replay-Schutz.
Verbesserung der Sicherheit: mTLS oder DPoP (Sender-Constrained Tokens), kurze TTLs (5-15 min), Schlüsselrotation (JWKS), Refresh-Token mit Rotation/Anti-Reuse, strikte Validierung 'aud/iss/exp/nbf/kid' und Policy-as-Code auf dem Gateway.

1) Lösungskarte: was wo anzuwenden ist

2) OAuth2/OIDC: Ströme und Kunden

2. 1 Ströme

Autorisierungscode + PKCE (Web/Mobile): Schützt den Autorisierungscode vor dem Abfangen.
Client Credentials: server↔server ohne Benutzer scopes ist das notwendige Minimum.
Device Code: für Geräte ohne Browser.
Refresh Token: nur für vertrauenswürdige Kunden; rotieren und reuse detection aktivieren.

2. 2 Client-Typen

Confidential (Server, BFF): Geheimnisse bewahren; Verwenden Sie mTLS.
Public (SPA/mobile): Das Geheimnis kann nicht → PKCE, DPoP, kurze TTLs und begrenzte Scopes gespeichert werden.

3) JWT: Struktur, Timing, Verifikation

3. 1 Felder (claims)

Obligatorische Angaben: "iss", "sub", "aud'," exp "," iat "," nbf "," jti "," scope "/" permissions "," tenant "(falls Mehrverleih)," kid ".

3. 2 Lebenszeit

Zugriffstoken: 5-15 Minuten.
Refresh Token: Tage/Wochen, rotieren bei jedem Austausch; Wenn Sie das alte erneut einreichen, blockieren Sie die Sitzung.
Uhr skew: Toleranz ≤ 60 Sek.

3. 3 JWKS und Schlüssel

Die Speicherung der Schlüssel in KMS/Vault, 'kid' ist obligatorisch.
Zwei aktive Schlüssel (Rolling), Re-Release alle 60-90 Tage oder bei einem Vorfall.
JWKS-Cache auf dem Gateway ≤ 5 Minuten, mit Auto-Behinderung.

3. 4 Verifizierung auf Gateway/Services

Überprüfen Sie: Signatur, 'aud' (zugelassene Dienste),' iss', 'exp/nbf', Sperrliste (Revocation).
Vertrauen Sie nicht auf Felder aus dem Körper, ohne die Signatur zu überprüfen; Ignorieren Sie' alg = none'.

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

4) Token-Bindung an den Client: mTLS, DPoP

mTLS (TLS Client Certificates): Ein Token wird nur ausgestellt und validiert, wenn ein Client-Zertifikat vorhanden ist → das Token ist außerhalb des Schlüssels + Zertifikat-Bündels unbrauchbar.
DPoP (Demonstration of Proof-of-Possession): Der Client signiert jede Anfrage mit einem einmaligen Schlüssel → Schutz vor Replay und Token-Diebstahl bei öffentlichen Clients.
Für kritische Routen (Zahlungsmutationen) - fordern Sie einen der Mechanismen.

5) Autorisierung: scopes, Rollen, ABAC

Scopes - minimale Aktionen ('Zahlungen: schreiben', 'Zahlungen: Status: lesen').
Roles - Aggregate für Admins; Verwenden Sie sie nicht direkt ohne Scopes.
ABAC - Attribute im Token ('tenant', 'country', 'kyc _ level', 'risk _ flags') → Richtlinien auf dem Gateway/OPA.
Richtlinie auf Routen-/Feldebene (GraphQL) und Domänenbetriebsebene (REST/gRPC).

6) HMAC-Signaturen: Webhooks und Partner

6. 1 Konzept

Jede Integration hat ihr eigenes Geheimnis.

Signatur über der kanonischen Zeile: 'timestamp + '\n' + Methode + '\n'+ Pfad + '\n'+ sha256 (Körper) '

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

Zeitfenster: ≤ 300 Sekunden Anfragen mit überfälliger/zukünftiger 'X-Timestamp' abzulehnen.
Idempotenz: 'X-Event-Id' auf TTL (24h) speichern - Duplikate verwerfen.

6. 2 Best Practices

Geheimnisse in KMS/Vault, Rotation alle 90 Tage.
Für öffentliche Kunden ist HMAC nicht geeignet (Geheimnis durchgesickert); Verwenden Sie OAuth2/DPoP.

7) Schutz vor Wiederholung, Brute Force und Lecks

Nonce/„ jti “für sensible Operationen; Blacklist der verwendeten IDs.
Rate/Quotas: nach Schlüssel/Kunde/Tenant/Route; „teure“ Operationen - separate Quoten.
IP/ASN/Geo allow-Listen für Partner und Webhooks.
Content-type allow ('application/json'), Begrenzung der Körpergröße.
PII-Maskierung in Protokollen; Verbot, Token/Geheimnisse zu protokollieren.

8) Fehler und Antworten (einheitliches Format)

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

• '401' ist kein/nicht valider Token (WWW-Authenticate).
• „403“ - unzureichende Rechte (Scope/ABAC).
• „429“ - Obergrenzen/Quoten.
• gRPC: `UNAUTHENTICATED`/`PERMISSION_DENIED`/`RESOURCE_EXHAUSTED`.

9) Fristen und Sitzungsrichtlinien

Access ≤ 15 Min. Refresh - Rotation + reuse detection (eingereicht alt - Session Recall).
Webhooks HMAC: TTL Signaturen ≤ 5 min; Neulieferung mit exponentiellem Backoff.
Sitzungs-/Schlüsselrückruf → sofortiger Zugriff auf die Revocationsliste (Cache auf dem Gateway ≤ 1 Minute).

10) Beobachtbarkeit und Audit

Korrelation durch 'trace _ id '/' span _ id'.
Metriken: auth Erfolgsrate, '401/403/429', OIDC/JWKS-Latenz, Rotationsrate, Refresh, DPoP/mTLS-Traffic-Anteil.
Audit-Log: „wer, wann, mit welchem 'sub/tenant/scope' was verursacht hat“, Schlüssel-/geheime Änderungen, fehlgeschlagene HMAC-Signaturen.

11) Einbettung in API Gateway

JWT-Validierung (JWKS-Cache) und OPA/ABAC am Gateway.
mTLS Profile für vertrauenswürdige Kunden/Partner.
HMAC-Verifizierung von Webhooks am Rand (vor internen Diensten).
Rate/Quota Richtlinien, Circuit-Breaker auf OIDC-Anbieter (JWK zwischenspeichern).
Feature-Flags: schnelle Deaktivierung des Clients/Schlüssels, Änderung des Signaturalgorithmus.

12) Mini-Schnipsel

Pseudo: JWT Verifikation

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: Webhook HMAC Check

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)

Beispiel für eine Scope-Richtlinie (OPA/Rego-Idee)

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

13) Playbooks der Vorfälle

Privater Schlüssel/JWT-Unterzeichner-Leck: Schlüssel-Neuausstellung, JWKS-Update, sofortige Deaktivierung des alten ('kid' → deny), Refresh-Behinderung, erzwungenes Logout.
Ersetzung von Webhooks: Rotation der Geheimnisse, IP-Allow-Liste, Verstärkung des Fensters' X-Timestamp', Neulieferung verpasster Ereignisse.
Replay/Brute Force: DPoP/mTLS auf kritischen Routen aktivieren, Kontingente einschränken, Zeitblöcke über IP/ASN, 'jti' -Blockliste aktivieren.
Outage OIDC: Degradation von zwischengespeicherten Token (grace), Circuit-Breaker-Anbieter, Kundenmitteilung.

14) Checklisten zur Umsetzung

• OAuth2: Code+PKCE (Web/Mobile), Client Credentials (server-to-server)
• TTL: Access ≤ 15 min, Refresh mit Rotation und Reuse Detection
• JWKS: zwei aktive Schlüssel, 'kid', Cache ≤ 5 min
• Webhooks: HMAC v1, 'X-Timestamp', 'X-Event-Id', Fenster ≤ 300 sec, Idempotenz
• Sender-constrained: mTLS/DPoP auf kritischen Strecken
• ABAC/OPA: scopes + tenant/risk in gateway policies
• Rate/Quota и 429; IP/ASN-Allow-Listen für Partner
• Audit und Alert (401/403/429, reuse refresh, HMAC-Signaturen)

• Keine Token/Geheimnisse/vollständige Karteikörper protokollieren
• PII-Maskierung; DSAR-Unterstützung; Aufbewahrungsfrist für Protokolle begrenzt

15) Anti-Muster

'alg = none' oder Vertrauen in ein Token ohne Signaturprüfung/JWKS.
Langlebige Access-Token (Stunden/Tag).
Ein gemeinsames HMAC-Geheimnis für alle Partner.
Webhooks ohne Timestamp/Idempotenz.
Refresh-Token ohne Rotation und ohne erneute Erkennung.
Keine' aud'/' iss' -Validierung und 'kid' -Rotation.
Speicherung von Geheimnissen in Umgebungsvariablen ohne KMS/Vault.

16) NFT/SLO (Benchmarks)

OIDC/JWKS Verfügbarkeit ≥ 99. 95% (Edge-Cache reduziert die Abhängigkeit).
JWT Validation Supplement auf dem Gateway ≤ 2-5 ms p95.
Authentifizierungsfehler („401“) ≤ 0. 5% des gesamten Datenverkehrs (ohne Bots).
Signierte Webhooks: Anteil der erfolgreich verifizierten ≥ 99. 9%, durchschnittliche Lieferverzögerung ≤ 3s.

Zusammenfassung

Kombinieren Sie die Mechanismen: OAuth2/OIDC + JWT für Benutzer und Rich-Server-Skripte, HMAC für Webhooks/einfache Partner und mTLS/DPoP für kritische Operationen. Halten Sie kurze TTLs, Schlüsselrotationen (JWKS), strenge ABAC/OPA-Richtlinien, schützen Sie die Konturen vor Replay und Lecks und automatisieren Sie alles auf Gateway-API-Ebene. So wird die Authentifizierung vorhersehbar, skalierbar und sicher - ohne Kompromisse bei UX und Monetarisierung.