Skip to main content
StartseiteBlogAnleitungenSo konfigurieren und rotieren Sie API-Schlüssel für die Sendungsverfolgung, ohne Ihre Integration zu beeinträchtigen

So konfigurieren und rotieren Sie API-Schlüssel für die Sendungsverfolgung, ohne Ihre Integration zu beeinträchtigen

17TRACK

Um API-Schlüssel für die Sendungsverfolgung sicher zu konfigurieren und zu rotieren, bewahren Sie die Zugangsdaten in einem serverseitigen Secrets Manager auf, ermitteln Sie jede Anwendung, die sie verwendet, und testen Sie einen Ersatzschlüssel, bevor Sie den alten Schlüssel außer Betrieb nehmen. Wenn Ihr Anbieter gleichzeitig gültige Zugangsdaten unterstützt, migrieren Sie die Verbraucher schrittweise und widerrufen Sie den alten Schlüssel erst nach der Verifizierung. Wenn der Ersatzschlüssel den bestehenden Schlüssel sofort ungültig macht, planen Sie einen koordinierten Wechsel mit dauerhaften Warteschlangen und Wiederherstellungsprüfungen, anstatt von null Ausfallzeit auszugehen.

So konfigurieren und rotieren Sie API-Schlüssel für die Sendungsverfolgung

Dieser Leitfaden richtet sich an Entwickler- und Betriebsteams, die Tracking-Integrationen in E-Commerce-Plattformen, Auftragsverwaltungssystemen, Lagerverwaltungssoftware und Kundenbenachrichtigungsdiensten betreiben. Ziel ist nicht lediglich, eine authentifizierte Anfrage zu stellen, sondern Sendungsregistrierungen, Tracking-Aktualisierungen und nachgelagerte Verarbeitung während der Änderung aufrechtzuerhalten.

Branded Order Tracking Solution
Verbessern Sie das Kundenerlebnis und steigern Sie Wiederholungskäufe mit markenbezogenem Tracking und automatisierten Benachrichtigungen.
Kostenlos testen →

Prüfen Sie, wie Ihr Anbieter Zugangsdaten verwaltet

Bevor Sie die Produktionskonfiguration ändern, müssen Sie den Lebenszyklus der Zugangsdaten des Anbieters verstehen. Eine Dashboard-Aktion mit der Bezeichnung „regenerate“ kann sich anders verhalten als „create another key“. Schließen Sie nicht allein aus der Beschriftung der Schaltfläche auf das Verhalten.

  • Authentifizierungsformat: Bestätigen Sie den erforderlichen Header oder einen anderen Authentifizierungsmechanismus, die Endpoint-Version und die Kontozuordnung.
  • Überschneidung: Können zwei Zugangsdaten gleichzeitig gültig bleiben? Widerruft das Erstellen eines Ersatzes die vorherigen Zugangsdaten sofort?
  • Berechtigungen: Ermitteln Sie, ob Schlüssel unterschiedliche Bereiche, Umgebungsbeschränkungen oder Zugriffskontrollen besitzen. Verwenden Sie diese Kontrollen, sofern verfügbar, und nehmen Sie nicht an, dass sie existieren.
  • Widerruf: Bestätigen Sie, wie eine Zugangsdaten deaktiviert wird und ob ein Ausbreitungsverhalten berücksichtigt werden muss.
  • Betriebliche Auswirkungen: Stellen Sie fest, ob Kontingente, registrierte Sendungen und Webhook-Einstellungen dem Konto, einer Anwendung oder einem einzelnen Schlüssel zugeordnet sind.

Beginnen Sie bei einer 17TRACK-Integration mit der offiziellen Tracking-API-Dokumentation und der Produktseite der Tracking API. Verwenden Sie die Dokumentation, um den Authentifizierungsvertrag Ihrer Integration zu bestätigen, und klären Sie das Verhalten des Zugangsdaten-Lebenszyklus über Ihre Kontosteuerung oder den Support, bevor Sie eine Rotation planen. Das folgende Verfahren ist ein betrieblicher Ablaufplan und keine Aussage darüber, dass 17TRACK einen bestimmten Ablauf für zwei Schlüssel oder zur Regenerierung anbietet.

17TRACK API Global Shipment Tracking Solution
Verbinden Sie sich über eine einzige API mit mehr als 3.500 Versanddienstleistern weltweit und verfolgen Sie Pakete einfach, präzise und zuverlässig.
Kostenlos testen →

Entscheidungsregel: Verwenden Sie eine Einführung mit sich überschneidenden Schlüsseln nur, wenn die gleichzeitige Gültigkeit bestätigt wurde. Andernfalls behandeln Sie die Rotation als koordinierten Austausch der Zugangsdaten. Eine Bereitstellungsstrategie kann kein Überschneidungsfenster schaffen, das der Anbieter nicht unterstützt.

Konfigurieren Sie den Schlüssel einmalig, ohne ihn im System zu verbreiten

Halten Sie die Authentifizierung auf dem Server

Speichern Sie die Produktionszugangsdaten in einem verwalteten Secrets Store oder einem gleichwertigen kontrollierten System. Lassen Sie die Anwendung sie über ihre Workload-Identität, Bereitstellungsplattform oder einen anderen genehmigten Mechanismus abrufen. Beschränken Sie den Lesezugriff auf benötigte Workloads und Betreiber.

Betten Sie den Schlüssel nicht in JavaScript im Browser, Bundles mobiler Anwendungen, Quellcode, Container-Images oder gemeinsam genutzte Konfigurationsbeispiele ein. Eine kundenorientierte Tracking-Seite sollte Ihr Backend aufrufen, das sich beim Tracking-Anbieter authentifizieren kann, ohne die Zugangsdaten des Anbieters offenzulegen.

Das OWASP Secrets Management Cheat Sheet unterstützt die zentrale Verwaltung von Geheimnissen, kontrollierten Zugriff, Auditing und Lebenszyklusverwaltung. Das REST Security Cheat Sheet rät außerdem davon ab, API-Schlüssel in URLs zu übermitteln, da Protokollierung und andere Verarbeitung sie offenlegen können. Befolgen Sie die dokumentierte Authentifizierungsmethode des Anbieters und entfernen Sie Authentifizierungswerte aus Anfrageprotokollen und Diagnoseexporten.

Trennen Sie Umgebungen und identifizieren Sie die bereitgestellte Version

Verwenden Sie separate Entwicklungs-, Staging- und Produktionszugangsdaten, sofern der Anbieter dies unterstützt. Wenn separate Zugangsdaten oder Konten nicht verfügbar sind, dokumentieren Sie diese Einschränkung und verhindern Sie, dass Nichtproduktionsaufträge unkontrollierte Schreibvorgänge in der Produktion ausführen.

Geben Sie dem Geheimnis eine logische Konfigurationsreferenz, etwa SHIPMENT_TRACKING_API_KEY. Speichern Sie die Version des Secrets Managers oder eine nicht geheime Bereitstellungsbezeichnung separat. Anhand dieser Bezeichnung können Betreiber die Frage „Welche Version verwendet dieser Worker?“ beantworten, ohne die Zugangsdaten selbst zu prüfen oder zu protokollieren.

Legen Sie ausdrücklich fest, wie Anwendungen Aktualisierungen erhalten. Ein Prozess, der eine Umgebungsvariable beim Start liest, benötigt in der Regel einen Neustart oder eine erneute Bereitstellung, um einen geänderten Wert zu übernehmen. Eine eingebundene Geheimnisdatei oder eine Laufzeitabfrage hat ein anderes Aktualisierungsverhalten. Die Aktualisierung des Secrets Stores beweist nicht, dass jeder laufende Prozess den Ersatz übernommen hat.

Stellen Sie vor der Rotation die Wiederherstellbarkeit von Anfragen sicher

Persistieren Sie Tracking-Aufgaben, bevor Sie sie an den Anbieter senden. Bewahren Sie bei der Sendungsregistrierung eine interne Vorgangs-ID, die Sendungsreferenz, den Verarbeitungsstatus und die Wiederholungshistorie auf. Halten Sie diese Geschäftsdaten von der Authentifizierung getrennt, damit Warteschlangenaufträge bei ihrer Ausführung die aktiven Zugangsdaten verwenden können.

Serialisieren Sie API-Schlüssel nicht in Nachrichten von Warteschlangen. Dadurch würden verzögerte Aufträge an veraltete Zugangsdaten gebunden und Geheimnisse in Warteschlangenspeicher, Dead-Letter-Warteschlangen und Debugging-Tools verbreitet.

Legen Sie bei Schreibvorgängen die Regeln des Anbieters für den Umgang mit Duplikaten fest, bevor Sie Wiederholungen aktivieren. Ein Timeout beweist nicht, dass die Registrierung fehlgeschlagen ist: Der Anbieter kann die Anfrage angenommen haben, bevor die Verbindung unterbrochen wurde. Verwenden Sie einen dokumentierten Idempotenzmechanismus, sofern vorhanden, oder gleichen Sie den Status der Sendung ab, bevor Sie sie erneut senden.

Erstellen Sie ein Verzeichnis der Verbraucher und eine Überwachungsbasis

Der am leichtesten übersehene Verbraucher ist häufig nicht die Hauptanwendung. Erfassen Sie geplante Importe, Warteschlangen-Worker, serverlose Funktionen, Verwaltungsskripte, Support-Tools, Disaster-Recovery-Bereitstellungen und Dienste, die derzeit auf null skaliert sind.

Notieren Sie für jeden Verbraucher seinen Eigentümer, die Umgebung, die Geheimnisreferenz, den Aktualisierungsmechanismus, den Ausführungszeitplan und die Bereitstellungsmethode. Identifizieren Sie lang laufende Aufträge, die Zugangsdaten im Speicher behalten können. Prüfen Sie außerdem wiederverwendbare HTTP-Clients, die nach Konfigurationsänderungen möglicherweise einen alten Authentifizierungs-Header beibehalten.

Erstellen Sie vor dem Wechsel eine Basislinie für:

  • Authentifizierungsfehler, gruppiert nach Dienst, Umgebung, Endpoint und Bereitstellungsversion.
  • Antwortlatenz des Anbieters, Timeouts, Rate-Limit-Antworten und Serverfehler.
  • Warteschlangentiefe, Alter des ältesten ausstehenden Auftrags und Umfang der Dead-Letter-Warteschlange.
  • Erfolgreiche Sendungsregistrierungen und ungelöste Registrierungsversuche.
  • Empfang und Verarbeitung von Webhooks, sofern Webhooks Bestandteil der Integration sind.

Trennen Sie den Integrationszustand von der Bewegung der Sendung. Ein Paket ohne neues Ereignis des Versanddienstleisters ist nicht zwangsläufig ein Hinweis auf einen API-Fehler. Während der Rotation sind erfolgreiche authentifizierte Anfragen und gesunde Verarbeitungswarteschlangen aussagekräftigere Signale als die Anzahl der Sendungen, deren Zustellstatus sich geändert hat.

Rotieren Sie mit sich überschneidenden Schlüsseln, sofern unterstützt

  1. Erstellen Sie den Ersatz, ohne den aktiven Schlüssel zu widerrufen. Prüfen Sie, dass die alten Zugangsdaten weiterhin gültig sind. Speichern Sie die neuen Zugangsdaten als eigene Geheimnisversion und beschränken Sie den Zugriff angemessen.
  2. Validieren Sie den Ersatz isoliert. Verwenden Sie eine dokumentierte, risikoarme Operation in der vorgesehenen Umgebung. Prüfen Sie sowohl das HTTP-Ergebnis als auch ein anwendungsspezifisches Ergebnis im Antworttext.
  3. Testen Sie einen repräsentativen Ablauf. Validieren Sie die Vorgänge, die Ihre Anwendung tatsächlich benötigt, nicht nur eine einfache Konnektivitätsprüfung. Wenn eine Registrierung erforderlich ist, verwenden Sie eine autorisierte Testsendung und berücksichtigen Sie mögliche Auswirkungen auf Kontingente oder Abrechnung.
  4. Stellen Sie den Ersatz für eine kleine Verbrauchergruppe bereit. Wechseln Sie eine Worker-Gruppe oder Anwendungsinstanz auf den Ersatz und prüfen Sie anschließend Authentifizierung, Verarbeitungsergebnisse und Warteschlangenverhalten.
  5. Führen Sie die Einführung für alle übrigen Verbraucher durch. Aktualisieren Sie das Verzeichnis, sobald jeder Dienst neu lädt oder neu gestartet wird. Beziehen Sie geplante Aufgaben, ruhende Workloads und Wiederherstellungskonfigurationen ein.
  6. Beobachten Sie ein angemessenes Verifizierungsfenster. Berücksichtigen Sie die relevante Lebensdauer der Worker, das Verhalten des Konfigurationscaches, die Wiederholungsverzögerung und den Auftragszeitplan. Es gibt keine allgemeingültige Wartezeit, die die Übernahme beweist.
  7. Widerrufen Sie den alten Schlüssel und prüfen Sie erneut. Achten Sie auf veraltete Verbraucher und entfernen Sie alte Geheimnisreferenzen gemäß Ihren Anforderungen an Aufbewahrung und Reaktion auf Vorfälle.

Wenn keine anbieterbasierte Nutzungsberichterstattung für Schlüssel verfügbar ist, verwenden Sie Bereitstellungsaufzeichnungen und von der Anwendung gemeldete Versionsbezeichnungen der Geheimnisse, um die Übernahme zu prüfen. Dies liefert betriebliche Nachweise, ersetzt aber kein vollständiges Verzeichnis der Verbraucher.

Behandeln Sie einen sofortigen Austausch als koordinierten Wechsel

Wenn das Ausstellen eines Ersatzes den alten Schlüssel sofort ungültig macht, kann eine ununterbrochene Authentifizierung durch eine schrittweise Bereitstellung nicht garantiert werden. Planen Sie den Übergang so, dass Arbeit sicher verzögert und nicht verloren wird.

  1. Bereiten Sie die Anwendungsbereitstellung, die Geheimnisreferenz, den Betreiberzugriff und Wiederherstellungsbefehle vor, bevor Sie die Zugangsdaten ersetzen.
  2. Halten Sie ausgehende Tracking-Anfragen an einer kontrollierten Grenze an, während Sie neue Aufgaben, soweit praktikabel, weiterhin in einem dauerhaften Speicher annehmen.
  3. Leeren Sie laufende Anfragen oder berücksichtigen Sie sie. Kennzeichnen Sie unklare Ergebnisse von Schreibvorgängen zur Abgleichung, anstatt sie automatisch als Fehler zu behandeln.
  4. Ersetzen Sie die Zugangsdaten des Anbieters, aktualisieren Sie den Secrets Store und aktualisieren Sie jeden Verbraucher.
  5. Führen Sie Authentifizierungs- und Ablaufprüfungen durch, bevor Sie den gesamten Rückstand freigeben.
  6. Nehmen Sie die Verarbeitung schrittweise wieder auf, beachten Sie die Rate-Limits des Anbieters und prüfen Sie auf doppelte Registrierungen.

Wenn die Integration nicht pausieren, Arbeit behalten oder Zugangsdaten vorhersehbar aktualisieren kann, beheben Sie diese Schwächen vor einer routinemäßigen Rotation. Bei einem vermuteten Sicherheitsvorfall kann jedoch eine sofortige Sperrung erforderlich sein, selbst wenn sie eine vorübergehende Unterbrechung verursacht.

Trennen Sie API-Authentifizierung und Webhook-Sicherheit

Ein ausgehender API-Schlüssel und ein eingehendes Geheimnis zur Webhook-Verifizierung erfüllen unterschiedliche Zwecke. Nehmen Sie nicht an, dass die Rotation des einen das andere ändert oder dass beide denselben Wert verwenden. Befolgen Sie die dokumentierte Webhook-Authentifizierung und das Zustellverhalten des Anbieters unabhängig voneinander.

Halten Sie während eines Wechsels ausgehender Zugangsdaten den Webhook-Empfang aktiv, sofern kein anderer Grund für eine Unterbrechung besteht. Validieren Sie eingehende Nachrichten gemäß der Spezifikation des Anbieters, nehmen Sie sie, sofern die Architektur dies zulässt, dauerhaft an, bevor Sie sie bestätigen, und gestalten Sie die Verarbeitung tolerant gegenüber doppelten Zustellungen.

Eine erfolgreiche authentifizierte API-Anfrage beweist nicht, dass Webhook-Zustellung oder -Verarbeitung fehlerfrei funktioniert. Prüfen Sie beide Pfade getrennt und ändern Sie beide Zugangsdaten nicht im selben Wartungsvorgang, sofern die Architektur des Anbieters dies nicht erfordert.

Beheben Sie Fehler, ohne eine Wiederholungswelle auszulösen

SymptomErste PrüfungenSichere Reaktion
Authentifizierungsfehler nach der BereitstellungGeheimnisversion, Header-Format, Umgebung, Leerzeichen, zwischengespeicherte ClientsKeine blinden Wiederholungen; Konfiguration korrigieren und eine Anfrage validieren.
Nur einige Worker schlagen fehlAlte Prozesse, verpasste Bereitstellungen, verzögerte Aufträge, veraltete GeheimniscachesBetroffene Verbraucher aktualisieren und Versionsbezeichnungen vergleichen.
Rate-Limits während der WiederherstellungFreigaberate des Rückstands und aggregierte ParallelitätWiederherstellung drosseln und dokumentierte Wiederholungsrichtlinien befolgen.
Registrierung läuft in einen TimeoutOb der Anbieter den Vorgang bereits angenommen hatVor einer erneuten Übermittlung abgleichen oder dokumentierte Idempotenz verwenden.

HTTP 401 betrifft im Allgemeinen fehlende oder ungültige Authentifizierung, während 403 bedeutet, dass der Server die Anfrage ablehnt. Antworttexte des Anbieters können die Ursache genauer erklären. Klassifizieren Sie nicht jeden 403 als abgelaufenen Schlüssel und gehen Sie nicht davon aus, dass jeder erfolglose Vorgang einen HTTP-Fehlerstatus verwendet.

Verwenden Sie für geeignete vorübergehende Fehler begrenzte Wiederholungen mit Backoff und Jitter. Das wiederholte Senden ungültiger Zugangsdaten wird diese nicht reparieren. Benachrichtigen Sie einen Betreiber, bewahren Sie die Arbeit auf und verhindern Sie, dass ein Konfigurationsfehler zu einer unkontrollierten Anforderungswelle wird.

Definieren Sie Rollback und Abschluss vor der Änderung

Bei einer Rotation mit sich überschneidenden Schlüsseln kann Rollback bedeuten, Verbraucher vorübergehend wieder auf die alten Zugangsdaten umzustellen, solange diese gültig und vertrauenswürdig sind. Nach dem Widerruf besteht diese Möglichkeit nicht mehr. Wenn der alte Schlüssel möglicherweise kompromittiert wurde, stellen Sie ihn nicht allein zur Wiederherstellung der Verfügbarkeit wieder her; geben Sie neue Zugangsdaten aus und setzen Sie den Prozess fort.

Schließen Sie die Rotation erst ab, wenn alle erfassten Verbraucher den Ersatz verwenden, die Authentifizierungsfehler auf ihre erwartete Basislinie zurückgekehrt sind, ausstehende Arbeit wieder verarbeitet wird, unklare Schreibvorgänge abgeglichen wurden und die Webhook-Verarbeitung weiterhin fehlerfrei ist. Dokumentieren Sie Eigentümer, Abschlusszeit, bereitgestellte Geheimnisversion und Widerrufsergebnis, ohne den Schlüsselwert aufzuzeichnen.

Wählen Sie für die laufende API-Sicherheit einen Rotationsplan auf Grundlage organisatorischer Richtlinien, des Risikos einer Offenlegung und der Fähigkeiten des Anbieters. Rotieren Sie außerhalb dieses Plans nach vermutetem Abfluss oder unangemessenem Zugriff. Ein wiederholbares, getestetes Verfahren ist nützlicher als eine beliebige Häufigkeit, die die Integration nicht sicher unterstützen kann.

FAQ

Kann ich einen Tracking-API-Schlüssel ohne Ausfallzeit rotieren?

Möglicherweise, wenn der Anbieter gleichzeitig gültige Zugangsdaten unterstützt und jeder Verbraucher vor dem Widerruf migriert werden kann. Wenn die Regenerierung den alten Schlüssel sofort deaktiviert, planen Sie eine kontrollierte Unterbrechung ausgehender Anfragen. Dauerhafte Warteschlangen können Arbeit während dieses Zeitraums bewahren, machen die Verbindung zum Anbieter jedoch nicht durchgehend verfügbar.

Sollten Warteschlangenaufträge für Sendungen den API-Schlüssel enthalten?

Nein. Speichern Sie den Sendungsvorgang und seine Verarbeitungsmetadaten und lösen Sie die aktiven Zugangsdaten erst bei der Ausführung durch den Worker auf. Dies verringert die Offenlegung von Geheimnissen und verhindert, dass verzögerte Aufträge wiederholt einen ungültig gemachten Schlüssel verwenden.

Löscht die Rotation des Schlüssels registrierte Sendungen?

Nehmen Sie kein Ergebnis an. Bestätigen Sie, ob registrierte Sendungen und zugehörige Einstellungen dem Konto, der Anwendung oder den Zugangsdaten zugeordnet sind. Eine erfolgreiche Authentifizierung allein beweist nicht, dass der Ersatz Zugriff auf die erwarteten Sendungsdaten hat.

Was soll ich tun, wenn ein Schlüssel in einem Repository oder Protokoll auftaucht?

Behandeln Sie ihn als potenziell kompromittiert. Widerrufen oder ersetzen Sie ihn unverzüglich, prüfen Sie verfügbare Zugriffs- und Nutzungsaufzeichnungen und befolgen Sie Ihr Verfahren zur Reaktion auf Sicherheitsvorfälle. Das Entfernen des sichtbaren Werts reicht nicht aus, da Kopien in Verlauf, Protokollexporten oder anderen Systemen verbleiben können.

Wie kann ich feststellen, ob ein alter geplanter Auftrag noch den vorherigen Schlüssel verwendet?

Prüfen Sie seine Geheimnisreferenz, bereitgestellte Konfiguration und das Aktualisierungsverhalten zur Laufzeit. Führen Sie ihn, sofern sicher, kontrolliert aus oder überprüfen Sie seine Bereitstellung vor dem nächsten geplanten Start. Ein ruhiges Dashboard beweist nicht, dass ein selten verwendeter Verbraucher migriert wurde.

Quellen