← Blog
10 Min. Lesezeit
|
Veröffentlicht
|
Aktualisiert

API-Key-Rotation: Erstellen, Setzen, Testen, Abschließen

So rotieren Sie API-Keys ohne Ausfallzeit: das Muster Erstellen, Setzen, Testen, Abschließen, Intervalle nach NIST und Besonderheiten bei Chaingateway.

Kapitel
C
Chaingateway Team
Blockchain-Experten

Geprüft von Maurice Sobiera

Isometrische Illustration rotierender API-Anmeldedaten

API-Key-Rotation heißt, einen aktiven Key nach Zeitplan oder nach einem Vorfall durch einen neuen zu ersetzen und dann den alten außer Betrieb zu nehmen. Das zuverlässige Muster hat vier Schritte: erstellen, setzen, testen, abschließen. Eine kurze Überlappung lässt beide Keys funktionieren, damit laufende Anfragen nicht scheitern. NIST und OWASP empfehlen beide, den Vorgang zu automatisieren.

Warum sollte ich API-Keys rotieren?

Rotation verkürzt die Zeit, in der ein abgeflossener Key für einen Angreifer nützlich ist. Jeder API-Key ist eine dauerhafte Schwachstelle. Ein Key kann über eine committete .env-Datei, einen kompromittierten CI-Runner oder den Laptop eines ehemaligen Mitarbeiters abfließen. Je länger der Key gültig bleibt, desto länger lässt sich ein Leck ausnutzen.

OWASP führt dieses Risiko als NHI7, Long-Lived Secrets, in seinen Top 10 für Non-Human Identities. Gemeint sind API-Keys und Tokens mit Ablaufdaten weit in der Zukunft oder ganz ohne Ablauf. OWASP nennt solche Secrets äußerst verbreitet, weil Rotation aufwendig ist und kurzlebige Alternativen nicht immer verfügbar sind.

Rotation zählt am meisten für diese Zugangsdaten:

  • Keys mit weitreichenden Rechten, etwa Admin-, Abrechnungs- oder Schreibzugriff auf Produktivdaten.
  • Zugangsdaten, die mehrere Dienste oder Teams teilen.
  • Alles, was in clientseitigen Code, mobile Apps oder Integrationen von Drittanbietern eingebettet ist.
  • Tokens, die ein öffentliches Repository berührt haben, auch nur kurz.

Ersetzen Sie den statischen Key, wo möglich, durch ein kurzlebiges Token von OAuth oder einem Workload-Identity-System. Ein Zugang, der von selbst abläuft, braucht keinen Rotationsjob.

Wie oft sollte ich API-Keys rotieren?

NIST nennt eine konkrete Zahl, und sie gilt für Signaturschlüssel. NIST IR 8587 sagt, dass Signaturschlüssel in Systemen mit hohen Auswirkungen eine maximale aktive Nutzungsdauer von 90 Tagen nicht überschreiten sollten. Bei Systemen mit mittleren und geringen Auswirkungen kann eine längere Dauer angemessen sein, sie sollte aber unter einem Jahr liegen. Der Bericht verlangt außerdem, die Kryptoperioden zu dokumentieren und automatisierte Rotation einzusetzen.

Für gewöhnliche API-Keys gibt NIST keine Intervalle vor. Die folgenden Werte sind unsere Vorschläge, abgeleitet aus dem risikobasierten Ansatz des Berichts. Sie sind keine NIST-Vorgabe.

ZugangsdatenVorgeschlagenes HöchstalterBegründung
Signaturschlüssel von Systemen mit hohen Auswirkungen90 Tage (NIST)Größter Schaden bei Missbrauch
API-Keys zwischen Diensten30 bis 90 TageHängt vom Umfang ab
CI/CD-Tokens30 TageTragen oft Deploy-Rechte
API-Keys für Nutzer90 Tage, und sofort nach einem Verdacht auf AbflussEs gibt viele Kopien

Balkendiagramm der vorgeschlagenen Kryptoperioden: Signaturschlüssel bis 90 Tage, Keys zwischen Diensten 30 bis 90 Tage, CI/CD-Tokens bis 30 Tage, API-Keys für Nutzer 90 Tage

Die Regel hinter der Tabelle ist einfach: Je größer der Schaden ist, den ein abgeflossener Zugang anrichten könnte, desto kürzer sollte seine nutzbare Dauer sein. Ein manueller 30-Tage-Zyklus ist für eine Handvoll Keys realistisch. Bei Dutzenden Diensten braucht es Automatisierung. NIST macht denselben Punkt. Kürzere Kryptoperioden zwingen Organisationen dazu, Rotation zu automatisieren und den Schlüsselwechsel regelmäßig zu üben.

Wo sollte ich API-Keys speichern?

Speichern Sie Keys in einem Secret Manager, der Secrets versioniert, Rotations-Hooks ausführt, Zugriffe begrenzt und jeden Lesezugriff protokolliert. Tabellen und geteilte .env-Dateien können das alles nicht. Prüfen Sie vor der Wahl vier Fähigkeiten:

  • Versionierung, damit das aktuelle und das vorherige Secret gleichzeitig existieren können.
  • Rotations-Hooks, die Ihre Rotationsfunktion nach Zeitplan oder Ereignis ausführen.
  • Begrenzung der Zugriffe, damit der Rotations-Agent nicht jedes Secret lesen kann.
  • Audit-Logs, die festhalten, wer welches Secret gelesen oder rotiert hat.

AWS Secrets Manager unterstützt geplante Rotation über eine Rotationsfunktion. HashiCorp Vault kann dynamische Secrets ausgeben, die sich selbst beenden. Cloud-eigene Schlüsseldienste, die an IAM-Rollen gebunden sind, übernehmen dieselbe Aufgabe.

Wo die Architektur es zulässt, verzichten Sie auf statische Keys. OWASP empfiehlt dynamische Secrets, wo möglich, weil sie die Angriffsfläche für die Wiederverwendung von Zugangsdaten verkleinern. Temporäre Zugangsdaten von AWS STS oder verwaltete Identitäten bei Azure und Google Cloud laufen nach Minuten oder Stunden ab. Dann bleibt nichts Langlebiges übrig, das rotiert werden müsste.

Was sind die Schritte Erstellen, Setzen, Testen, Abschließen?

Die vier Schritte sind das Muster, das die OWASP-Spickzettel für Rotationsfunktionen in Serverless-Umgebungen beschreiben. Sie gelten für jeden Secret Manager und jedes eigene Skript.

  1. Erstellen: eine neue Secret-Version erzeugen, ohne die aktive anzufassen.
  2. Setzen: die neue Zugangsdaten an den abhängigen Dienst oder in den Konfigurationsspeicher übertragen.
  3. Testen: eine Integrationsprüfung ausführen, die belegt, dass das neue Secret authentifiziert.
  4. Abschließen: das neue Secret als aktiv setzen und das alte widerrufen oder seine Löschung planen.

Den Schritt, den Teams auslassen, ist die Überlappung zwischen „Setzen“ und „Abschließen“. NIST beschreibt sie als überlappende Akzeptanz alter und neuer Keys. Die Rotation sollte den Schlüsselwechsel vor dem Ablauf planen, damit Empfänger beide Versionen für eine Weile akzeptieren. Die richtige Länge der Überlappung hängt von Ihrem System ab. Sie muss länger sein als Ihre längste laufende Anfrage und länger als die Zeit, die Ihre Clients brauchen, um den neuen Wert zu übernehmen, einschließlich der Lebensdauer von Caches. Legen Sie eine Zahl fest und testen Sie sie im Staging.

AuslöserPassend fürBerechtigungsmodell
GeplantVorhersehbarer Rhythmus, etwa 30 oder 90 TageRotationsrolle auf einen Secret-Pfad begrenzt
EreignisgesteuertKompromittierung erkannt, Ausscheiden eines MitarbeitersErhöht, aber zeitlich begrenzt und nach dem Lauf widerrufen
ManuellEinmalige Prüfungen, Einarbeitung neuer DiensteMenschliche Freigabe plus MFA

Der Rotations-Agent sollte so wenig Rechte wie möglich haben: Schreibzugriff auf ein Secret und nichts Weiteres.

Was sollte meine Rotations-Checkliste enthalten?

Gehen Sie vier Punkte durch, bevor Sie etwas automatisieren.

  1. Sichern Sie das aktuelle Secret und testen Sie das Zurückrollen, damit es nicht nur Theorie bleibt.
  2. Bauen Sie einen Integrationstest, der das neue Zugangsdatum gegen einen echten Endpunkt prüft.
  3. Legen Sie eine Rotationsrolle an, die genau auf ein Secret begrenzt ist.
  4. Protokollieren Sie jedes Rotationsereignis in Ihrem Audit-Trail.

Achten Sie auf drei wiederkehrende Fehlerstellen. Anwendungen speichern Zugangsdaten im Speicher und sehen den neuen Key erst nach einem Neustart. Anbieter begrenzen die Rate des Endpunkts zum Erstellen von Keys, wenn Sie viele Secrets in einem Stapel rotieren. Veraltete Clients nutzen einen widerrufenen Key weiter, nachdem die Überlappung beendet ist.

Protokollieren Sie, wer oder was jede Rotation ausgelöst hat, eine maskierte Version des alten und neuen Keys, den Modus (geplant, manuell oder Notfall) und das Ergebnis. Beobachten Sie einen plötzlichen Anstieg der Anfragen eines Keys, Aufrufe von IP-Adressen oder Regionen, die der Key nie zuvor genutzt hat, und Anfragen mit einem Key, der längst abgelaufen sein müsste. Führen Sie Repository-Scans auf fest eingetragene Keys aus und pflegen Sie ein Inventar. Ein Key außerhalb des Inventars wird nie rotiert.

Wie rotiere ich Chaingateway-Zugangsdaten?

Eine Chaingateway-Integration hat drei Arten von Secrets, und jede rotiert anders.

Der API-Token authentifiziert Ihre Anfragen als Bearer-Token. Sie erstellen Tokens im Account-Panel unter API Tokens und geben jedem einen Namen. Verwenden Sie pro Umgebung einen Namen, etwa Development, Staging und Production. Zum Rotieren erstellen Sie einen neuen Token, verteilen ihn über Ihren Secret Manager, prüfen, dass Anfragen gelingen, und widerrufen dann den alten. Um zu begrenzen, was ein abgeflossener Token bewirken kann, aktivieren Sie die IP-Whitelist (siehe unten). So darf nur die Adresse Ihres Servers ihn nutzen.

Das Webhook-Secret, das persönliche Secret, signiert jeden Webhook über den Header X-Signature. Die Dokumentation zur Webhook-Sicherheit hält fest, dass ein neues Secret bei Webhook-Benachrichtigungen sofort wirkt. Auf der Senderseite können Sie nicht zwei Secrets gleichzeitig betreiben. Die Überlappung muss deshalb auf Ihrem Empfänger liegen. Prüfen Sie eine kurze Zeit gegen das neue und das alte Secret und entfernen Sie danach das alte.

import { createHmac, timingSafeEqual } from "node:crypto";
// Accept the new secret and, during rotation only, the previous one
const secrets = [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET_PREVIOUS].filter(Boolean);
function signatureValid(txid, received) {
return secrets.some((secret) => {
const expected = createHmac("sha256", secret).update(txid).digest("base64");
return (
expected.length === received.length &&
timingSafeEqual(Buffer.from(expected), Buffer.from(received))
);
});
}

Benachrichtigungen, die Ihr Server während der Umstellung abgelehnt hat, erscheinen in der Liste der fehlgeschlagenen Benachrichtigungen. Chaingateway sendet sie nicht automatisch erneut. Lesen Sie die Liste mit GET /api/v2/{chain}/webhooks/notifications/failed und senden Sie jeden Eintrag mit POST /api/v2/{chain}/webhooks/notifications/{id}/retry erneut. Der Leitfaden zu den Zustellungsgarantien von Webhooks behandelt das ausführlicher.

Wallet-Passwörter schützen Adressen, die Sie mit einem Passwort erstellt haben. Sie ändern eines mit POST /api/v2/ethereum/addresses/{address}, die Anfrage nimmt old_password und new_password entgegen. Dieselbe Route gibt es für die anderen Chains. Chaingateway speichert keine Passwörter. Legen Sie das neue deshalb im Secret Manager ab, bevor Sie es ändern. Ein verlorenes Passwort lässt sich nicht wiederherstellen.

Was leistet die IP-Whitelist von Chaingateway?

Die IP-Whitelist ist eine Kontoeinstellung, die Ihren API-Key auf die Server-Adressen beschränkt, die Sie auflisten. Sie wurde am 21. Juni 2021 veröffentlicht. Sie schalten sie in den Einstellungen des Account-Panels ein und tragen dann die erlaubten Adressen ein. Eine Anfrage von jeder anderen Adresse wird abgelehnt, auch wenn der Key stimmt. Ein abgeflossener Key ist deshalb von jedem Rechner aus nutzlos, den Sie nicht aufgelistet haben.

Tragen Sie beim Einschalten die Adresse Ihres eigenen Servers ein, sonst werden auch Ihre eigenen Anfragen abgelehnt. Listen Sie die öffentliche Adresse auf, die Ihr Server im Internet verwendet. Private Bereiche wie 10.0.0.0/8 und 192.168.0.0/16 sind in RFC 1918 definiert und kommen nie als Absender einer Anfrage bei der API an. Hinter einem NAT-Gateway tragen Sie die Adresse des Gateways ein. Dann sind alle Rechner dahinter erlaubt, nicht nur einer.

Die Whitelist gilt für Anfragen, die Sie an die API senden. Für Webhooks gilt sie nicht, denn diese laufen von Chaingateway zu Ihrem Endpoint. Prüfen Sie Webhooks wie oben beschrieben über die Signatur.

Whitelist und Rotation begrenzen Unterschiedliches. Die Whitelist begrenzt, wo ein gestohlener Key funktioniert. Die Rotation begrenzt, wie lange er funktioniert. Nutzen Sie beides. Wenn Ihre Server auf neue Adressen umziehen, aktualisieren Sie die Liste vor dem Umzug, damit nicht Ihr eigener Datenverkehr abgelehnt wird.

Wann ergeben statische API-Keys keinen Sinn mehr?

Statische Keys sind für interne Werkzeuge mit geringem Risiko vertretbar. Sobald Sie eine API externen Partnern öffnen oder Finanzdaten verarbeiten, wechseln Sie zu OIDC oder JWT-basierter Authentifizierung mit kurzen Laufzeiten. Beginnen Sie mit einem Dienst mit wenig Verkehr. Prüfen Sie, dass Ihre Rotationsautomatisierung unter echtem Verkehr hält, und weiten Sie sie dann aus. Eine Rotationsrichtlinie, die durchgesetzt wird und nicht nur empfohlen ist, gehört zu den wirksamsten Änderungen, die ein Sicherheitsteam vornehmen kann.

Screenshot der Chaingateway-Startseite mit der Überschrift zu einer einheitlichen Blockchain-API für Krypto-Zahlungen und Webhooks und einer Schaltfläche für die 7-tägige kostenlose Testphase

Chaingateway deckt Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Smart Chain und Arbitrum mit einer REST-API und einer Authentifizierungsschicht ab. Sie verwalten dadurch keinen eigenen Lebenszyklus für Zugangsdaten je Chain. Das Webhook-Feature liefert Einzahlungsbenachrichtigungen. Die Tarife beginnen bei 49 € pro Monat auf der Preisseite. Die 7-tägige kostenlose Testphase braucht keine Karte.

Quellen

Empfohlen

Erstellt mit BabyLoveGrowth zum Aufbau von Backlinks

Häufig gestellte Fragen

Einen API-Key zu rotieren heißt, einen neuen Zugang zu erzeugen, der den aktiven ersetzt, und den alten außer Betrieb zu nehmen, sobald alle abhängigen Systeme umgestellt sind. Richtig umgesetzt läuft das als automatisierter Zyklus aus Erstellen, Setzen, Testen und Abschließen mit einer kurzen Überlappung, in der beide Keys funktionieren.

Das hängt vom Risiko ab. NIST IR 8587 sagt, dass Signaturschlüssel von Systemen mit hohen Auswirkungen nicht länger als 90 Tage aktiv bleiben sollten. Für gewöhnliche API-Keys nennt der Bericht keine Zahl. Wählen Sie das Intervall deshalb nach dem Umfang des Keys. Kürzer ist besser für CI/CD-Tokens und für alles mit weitreichendem Zugriff.

Rotation begrenzt den Schaden durch einen abgeflossenen oder gestohlenen Zugang, weil sie die Zeit verkürzt, in der der Key gültig ist. OWASP führt langlebige Secrets in seinen Top 10 für Non-Human Identities als NHI7.

Automatisieren Sie den Vorgang mit einem Secret Manager, folgen Sie dem Muster Erstellen, Setzen, Testen, Abschließen und halten Sie ein Übergangsfenster, in dem alter und neuer Key beide funktionieren. So vermeiden Sie den Ausfall, der entsteht, wenn alle abhängigen Dienste gleichzeitig umgestellt werden.

Ja. Chaingateway signiert Webhooks mit HMAC-SHA256 im Header X-Signature, sodass Sie die Echtheit prüfen können. Ändern Sie das persönliche Secret, wirkt das neue Secret sofort. Ihr Empfänger sollte deshalb für kurze Zeit beide Secrets akzeptieren.

So entstehen diese Artikel

Möchten Sie das selbst umsetzen? API-Key erhalten — 7 Tage kostenlos testen, keine Karte nötig — oder werfen Sie einen Blick auf Blockchain-API für die vollständige Endpoint-Referenz.

C
Chaingateway Team
Blockchain-Experten

Das Chaingateway-Team hat es sich zur Aufgabe gemacht, die Blockchain-Integration für Entwickler weltweit zu vereinfachen.