Geheime Daten in der Reactor-API

In der Reactor-API sind geheime Daten eine Ressource, die einen Authentifizierungsnachweis darstellt. Geheime Daten werden bei der Ereignisweiterleitung verwendet, um sich für einen sicheren Datenaustausch bei einem anderen System zu authentifizieren. Daher können geheime Daten nur in Ereignisweiterleitungs-Eigenschaften erstellt werden (Eigenschaften, deren platform-Attribut auf edge festgelegt ist).

Es gibt derzeit drei unterstützte Typen von geheimen Daten, die in dem Attribut type_of aufgeführt werden:

Dieses Handbuch bietet einen allgemeinen Überblick darüber, wie geheime Daten für die Verwendung in der Ereignisweiterleitung konfiguriert werden. Ausführliche Anleitungen zum Verwalten von geheimen Daten in der Reactor-API, einschließlich Beispiel-JSON der Struktur geheimer Daten, finden Sie im Handbuch zum Secrets-Endpunkt.

Anmeldeinformationen

Geheime Daten enthalten ein Attribut credentials, das die entsprechenden Werte der Anmeldeinformationen enthält. Wann Erstellen eines Geheimnisses in der API, weist jeder geheime Typ verschiedene erforderliche Attribute auf, wie in den folgenden Abschnitten dargestellt:

• token
• simple-http
• oauth2-client_credentials
• oauth2-google

token

Geheime Daten mit einem type_of-Wert von token erfordern nur ein einziges Attribut unter credentials:

Das Token wird als statischer Wert gespeichert, weswegen die Eigenschaften expires_at und refresh_at auf null festgelegt werden, wenn die geheimen Daten erstellt werden.

simple-http

Geheime Daten mit einem type_of-Wert von simple-http erfordern die folgenden Attribute unter credentials:

Wenn die geheimen Daten erstellt werden, werden die beiden Attribute mit einer BASE64-Codierung von username:password ausgetauscht. Nach dem Austausch sind die Eigenschaften expires_at und refresh_at auf null festgelegt.

oauth2-client_credentials

Geheime Daten mit einem type_of-Wert von oauth2-client_credentials erfordern die folgenden Attribute unter credentials:

Wenn geheime Daten vom Typ oauth2-client_credentials erstellt oder aktualisiert werden, werden client_id und client_secret (und gegebenenfalls options) in einer POST-Anfrage an die token_url entsprechend dem Client-Anmeldedaten-Fluss des OAuth-Protokolls ausgetauscht.

Wenn der Autorisierungs-Service mit 200 OK und einem JSON-Antworttext antwortet, wird der Text geparst, das access_token in die Edge-Umgebung verschoben und expires_in verwendet, um die Attribute expires_at und refresh_at für die geheimen Daten zu berechnen. Wenn keine Umgebungsverknüpfung für die geheimen Daten vorhanden ist, wird das access_token verworfen.

Ein Austausch von Anmeldeinformationen wird unter folgenden Bedingungen als erfolgreich betrachtet:

• expires_in ist größer als 28800 (acht Stunden).
• refresh_offset ist kleiner als der Wert von expires_in minus 14400 (vier Stunden). Wenn beispielsweise expires_in 36000 (zehn Stunden) ist und refresh_offset 28800 (acht Stunden), wird der Austausch als fehlgeschlagen betrachtet, weil 28800 größer als 36000 - 14400 (21600) ist.

Wenn der Austausch erfolgreich ist, wird das Statusattribut der geheimen Daten auf succeeded festgelegt und es werden zudem Werte für expires_at und refresh_at definiert:

• expires_at ist die aktuelle UTC-Zeit plus der Wert von expires_in.
• refresh_at ist die aktuelle UTC-Zeit plus der Wert von expires_in abzüglich des Werts von refresh_offset. Wenn beispielsweise expires_in 43200 (zwölf Stunden) ist und refresh_offset 14400 (vier Stunden), würde die Eigenschaft refresh_at auf 28800 (acht Stunden) nach der aktuellen UTC-Zeit festgelegt.

Wenn der Austausch aus irgendeinem Grund fehlschlägt, wird das Attribut status_details im Objekt meta mit relevanten Informationen aktualisiert.

Aktualisieren von geheimen Daten des Typs oauth2-client_credentials

Wenn geheime Daten des Typs oauth2-client_credentials einer Umgebung zugewiesen wurden und ihr Status succeeded (die Anmeldeinformationen wurden erfolgreich ausgetauscht) lautet, wird zum Zeitpunkt refresh_at automatisch ein neuer Austausch durchgeführt.

Wenn der Austausch erfolgreich ist, wird das Attribut refresh_status im Objekt meta auf succeeded festgelegt und expires_at, refresh_at und activated_at werden entsprechend aktualisiert.

Wenn der Austausch fehlschlägt, erfolgen drei weitere Versuche, den Vorgang auszuführen, wobei der letzte Versuch spätestens zwei Stunden vor Ablauf des Zugriffs-Tokens stattfindet. Wenn alle Versuche fehlschlagen, wird das Attribut refresh_status_details aus dem Objekt meta mit relevanten Details aktualisiert.

oauth2-google

Geheimnisse mit type_of Wert von oauth2-google erfordert das folgende Attribut unter credentials:

Nach der Erstellung oauth2-google geheim ist, enthält die Antwort eine meta.authorization_url -Eigenschaft. Sie müssen diese URL kopieren und in einen Browser einfügen, um den Google-Authentifizierungsfluss abzuschließen.

Erneutes Autorisieren eines oauth2-google secret

Die Autorisierungs-URL für eine oauth2-google geheim läuft eine Stunde nach der Erstellung des Geheimnisses ab (wie durch meta.authorization_url_expires_at). Danach muss das Geheimnis erneut autorisiert werden, um den Authentifizierungsprozess zu verlängern.

Siehe Abschnitt Endpunktleitfaden für Geheimnisse für Details zur Neuautorisierung eines oauth2-google geheim durch eine PATCH-Anfrage an die Reactor-API.

Umgebungsbeziehung

Beim Erstellen geheimer Daten müssen Sie die Umgebung angeben, in der sie existieren werden. Geheime Daten werden sofort in der Umgebung bereitgestellt, in der sie erstellt werden.

Geheime Daten können jeweils nur mit einer Umgebung verknüpft werden. Sobald die Beziehung zwischen geheimen Daten und einer Umgebung hergestellt ist, können die geheimen Daten nicht mehr aus der Umgebung gelöscht werden und sie können nicht mit einer anderen Umgebung verknüpft werden.

Nachdem die Anmeldeinformationen von geheimen Daten erfolgreich ausgetauscht wurden, wird das Austausch-Artefakt (die Token-Zeichenfolge für token, der Base64-codierte String für simple-http oder das Zugriffs-Token für oauth2-client_credentials) sicher in der Umgebung gespeichert, um die geheimen Daten mit der Umgebung zu verknüpfen.

Nachdem das Austausch-Artefakt erfolgreich in der Umgebung gespeichert wurde, wird das Attribut activated_at der geheimen Daten auf die aktuelle UTC-Zeit festgelegt, sodass jetzt mithilfe eines Datenelements darauf verwiesen werden kann. Siehe den nächsten Abschnitt mit weiteren Informationen zum Verweisen auf geheime Daten.

Verweisen auf geheime Daten

Um auf geheime Daten zu verweisen, müssen Sie ein Datenelement des Typs Geheime Daten (bereitgestellt von der Core-Erweiterung) in einer Ereignisweiterleitungs-Eigenschaft erstellen. Beim Konfigurieren dieses Datenelements werden Sie aufgefordert, anzugeben, welche geheimen Daten für jede Umgebung verwendet werden sollen. Anschließend können Sie Regeln erstellen, die auf ein Geheime-Daten-Datenelement verweisen, z. B. im Header für einen HTTP-Aufruf.

Zur Laufzeit wird das Geheime-Daten-Datenelement durch das entsprechende Geheime-Daten-Austausch-Artefakt ersetzt, das in der Umgebung gespeichert ist.

Nächste Schritte

In diesem Handbuch wurden die Grundlagen für die Arbeit mit geheimen Daten in der Reactor-API behandelt. Weitere Informationen zum Verwalten von geheimen Daten mithilfe von API-Aufrufen finden Sie im Handbuch zum Secrets-Endpunkt.