Implementierung eines OAuth 2.0-Autorisierungscodeflusses mit Token-Speicherung in Jitterbit Studio

Einführung

Der OAuth 2.0-Autorisierungscodefluss ermöglicht es einer Studio-Operation, auf eine API eines Drittanbieters im Namen eines bestimmten Benutzers zuzugreifen, indem die delegierten Anmeldeinformationen dieses Benutzers anstelle eines gemeinsamen Dienstkontos verwendet werden. Dieser Leitfaden behandelt den vollständigen Fluss: den Aufbau der Autorisierungs-URL, den Empfang des Autorisierungscodes an einem Callback-Endpunkt, den Austausch des Codes gegen Zugriffs- und Aktualisierungstoken, die Speicherung des Aktualisierungstokens in Cloud Datastore und das Aktualisieren des Zugriffstokens bei nachfolgenden Ausführungen ohne Benutzerinteraktion.

Die Beispiele in diesem Leitfaden verwenden Google als Autorisierungsanbieter. Dasselbe Muster gilt für jeden OAuth 2.0-Anbieter, der den Autorisierungscode-Grant-Typ unterstützt: Ersetzen Sie die anbieter-spezifischen URLs, Scopes und Parameternamen durch die Werte Ihres Zielservices.

Verwenden Sie dieses Muster, wenn:

• Die Ziel-API Benutzerberechtigungen erfordert, die ein Dienstkonto nicht bereitstellen kann.
• Sie langfristigen Zugriff mit Aktualisierungstokens ohne wiederholte manuelle Autorisierung benötigen.
• Sie einen KI-Agenten oder einen automatisierten Workflow erstellen, der auf Benutzerpostfächer, Kalender oder Dokumente zugreift.

Für APIs, die API-Schlüssel oder Client-Anmeldeinformationen anstelle von Benutzerautorisierung verwenden, siehe Verwalten von Endpunkt-Anmeldeinformationen und Aufrufen einer REST-API mit dem HTTP v2-Connector.

Dieser Leitfaden geht davon aus:

• Eine benutzerdefinierte API ist konfiguriert und im API-Manager in derselben Umgebung wie das Projekt veröffentlicht.
• Ein Cloud Datastore-Schlüsselspeicher existiert oder wird erstellt, um benutzerspezifische Token-Datensätze zu halten. Siehe Speichern und Abrufen des Sitzungsstatus mit Cloud Datastore für die Einrichtungsschritte.
• Das Projekt hat eine Möglichkeit, eine URL an den Benutzer zu übermitteln, z. B. eine Slack-Nachricht oder eine App Builder-Oberfläche.

Entwurfsmuster

Drei Operationen implementieren den OAuth 2.0-Autorisierungscodefluss:

Die Connect-Operation erstellt die Autorisierungs-URL und liefert sie an den Benutzer. Die OAuth Callback-Operation empfängt den Autorisierungscode, wenn der Anbieter den Browser des Benutzers umleitet, tauscht den Code gegen Tokens aus und speichert das Refresh-Token für die zukünftige Verwendung. Die Check Auth-Operation wird vor jedem API-Aufruf ausgeführt: Sie liest das gespeicherte Refresh-Token aus dem Cloud Datastore und tauscht es gegen ein neues Zugriffstoken aus.

Teil 1: Registrieren Sie die OAuth-Anwendung und speichern Sie die Anmeldeinformationen

Bevor Sie Skripte schreiben, registrieren Sie Studio als OAuth-Anwendung beim Autorisierungsanbieter und speichern Sie die resultierenden Anmeldeinformationen als Projektvariablen.

Registrieren Sie die Anwendung

Erstellen Sie in der Entwicklerkonsole Ihres OAuth-Anbieters (zum Beispiel in der Google Cloud Console) eine OAuth 2.0-Anmeldeinformation vom Typ Webanwendung und konfigurieren Sie:

• Autorisierte Umleitungs-URIs: Fügen Sie die vollständige URL des Callback-Endpunkts hinzu, den Sie in Teil 2 erstellen werden. Zum Beispiel: https://<your-agent-host>/<environment>/<version>/<service-root>/oauth/callback. Sie müssen diese URL kennen, bevor Sie die Registrierung abschließen.

Der Anbieter stellt eine Client-ID und ein Client-Geheimnis aus.

Speichern Sie Anmeldeinformationen als Projektvariablen

Öffnen Sie in Studio das Projektaktionsmenü und wählen Sie Projektvariablen. Erstellen Sie die folgenden Projektvariablen mit ihren Werten verborgen:

• client_id: Die vom Anbieter ausgegebene Client-ID der OAuth-Anwendung.
• client_secret: Das Client-Geheimnis der OAuth-Anwendung.
• redirect_uri: Die vollständige Callback-URL, die in der Anbieter-Konsole konfiguriert ist.

Verweisen Sie in Skripten auf diese Variablen mit dem $-Präfix (zum Beispiel $client_id, $client_secret, $redirect_uri).

Teil 2: Erstellen Sie den Callback-Endpunkt

Der Callback-Endpunkt empfängt den Autorisierungscode vom Anbieter, nachdem der Benutzer den Zugriff genehmigt hat. Erstellen Sie ihn, bevor Sie Skripte schreiben, damit die vollständige URL verfügbar ist, um sie in der Anbieter-Konsole zu konfigurieren.

Erstellen Sie die Callback-Operation

1. Erstellen Sie in Studio eine neue Operation. Nennen Sie sie OAuth Callback oder einen ähnlichen Namen.

2. Fügen Sie einen Script Schritt als ersten Schritt hinzu. Lassen Sie den Skriptkörper vorerst leer. Sie werden die Callback-Logik in Teil 4 hinzufügen.

Veröffentlichen Sie die Callback-Operation als API-Endpunkt

Befolgen Sie Eine Studio-Operation als REST-API bereitstellen, um die OAuth Callback-Operation zu veröffentlichen. Stellen Sie beim Konfigurieren des Endpunkts ein:

• Methode: GET. OAuth-Anbieter leiten den Browser des Benutzers mit einer GET-Anfrage und Abfrageparametern zur Callback-URL um.
• Pfad: /oauth/callback (oder einen beliebigen Pfad, der mit der Umleitungs-URI übereinstimmt, die Sie beim Anbieter registrieren werden).
• Antworttyp: Variabel. Das Callback-Skript setzt $jitterbit.api.response.body und $jitterbit.api.response.headers.Content_Type, um eine HTML-Bestätigungsseite bereitzustellen.

Kopieren Sie die veröffentlichte Endpunkt-URL. Verwenden Sie sie als Wert der Projektvariablen redirect_uri und registrieren Sie sie beim Anbieter als autorisierte Umleitungs-URI.

Teil 3: Erstellen Sie die Autorisierungs-URL

Die Connect-Operation erstellt die Autorisierungs-URL und liefert sie an den Benutzer.

Erstellen Sie die Connect-Operation

Erstellen Sie eine neue Operation. Nennen Sie sie Connect oder einen ähnlichen Namen. Fügen Sie einen Skript-Schritt mit folgendem Skript hinzu:

<trans>
$authUrl = "https://accounts.google.com/o/oauth2/v2/auth"
    + "?client_id=" + $client_id
    + "&redirect_uri=" + URLEncode($redirect_uri)
    + "&response_type=code"
    + "&scope=" + URLEncode("https://mail.google.com/ openid email")
    + "&access_type=offline"
    + "&prompt=consent";
</trans>

Die wichtigsten Parameter:

• response_type=code: Fordert den Autorisierungscode-Grant-Typ an.
• scope: Die Berechtigungen, die die Anwendung anfordert. Trennen Sie mehrere Scopes mit Leerzeichen und URL-kodieren Sie den kombinierten String mit URLEncode. Passen Sie die Scope-Werte an, um den Anforderungen Ihrer Ziel-API zu entsprechen.
• access_type=offline: Weist den Anbieter an, zusätzlich zum Zugriffstoken ein Aktualisierungstoken auszustellen.
• prompt=consent: Erzwingt, dass der Zustimmungsbildschirm angezeigt wird, selbst wenn der Benutzer die Anwendung zuvor autorisiert hat. Dies stellt sicher, dass jedes Mal ein neues Aktualisierungstoken ausgestellt wird.

Ersetzen Sie die URL des Google-Autorisierungsendpunkts und die Werte für den Scope durch die Ihres Zielanbieters.

Liefern Sie die URL an den Benutzer

Nachdem Sie die URL erstellt haben, liefern Sie sie so, dass der Benutzer sie in einem Browser öffnen kann. Um die URL als Slack-ephemerale Nachricht zu senden (zum Beispiel in einem Agenten, der Slack als Schnittstelle verwendet):

<trans>
$jitterbit.api.response = "{\"response_type\": \"ephemeral\", \"text\": \"Um Ihr Konto zu verbinden, öffnen Sie diesen Link: " + $authUrl + "\"}";
</trans>

Alternativ können Sie die URL als einfache API-Antwort zurückgeben oder sie in den E-Mail-Text einfügen.

Teil 4: Verarbeiten Sie den Callback und tauschen Sie den Autorisierungscode aus

Der OAuth Callback-Vorgang wird ausgeführt, wenn der Anbieter den Browser des Benutzers zur registrierten Callback-URL umleitet. Er muss den Autorisierungscode extrahieren, eine HTML-Bestätigungsseite im Browser bereitstellen, den Code gegen Tokens austauschen und das Refresh-Token speichern.

Schritt 1: Extrahieren Sie den Autorisierungscode und stellen Sie die Bestätigungsseite bereit

Öffnen Sie im OAuth Callback-Vorgang den Skriptschritt und fügen Sie hinzu:

<trans>
$authCode = $jitterbit.api.request.parameters.code;

$jitterbit.api.response.body = "<html><body><h2>Connected successfully!</h2><p>You can close this window and return to the application.</p></body></html>";
$jitterbit.api.response.headers.Content_Type = "text/html";
$jitterbit.api.response.status_code = "200";

RunOperation("<TAG>Operations/Exchange Token</TAG>");
</trans>

$jitterbit.api.request.parameters.code enthält den Autorisierungscode aus der Abfragezeichenfolge der Umleitungs-URL. Der Antwortkörper, der Inhaltstyp und der Statuscode, die hier festgelegt sind, werden an den Browser zurückgegeben, wenn der Vorgang abgeschlossen ist. RunOperation ruft den Exchange Token-Vorgang synchron auf: Der Token-Austausch erfolgt, bevor die Antwort zurückgegeben wird, und die globale Variable authCode steht dem aufgerufenen Vorgang zur Verfügung.

Schritt 2: Konfigurieren Sie die Verbindung zum Token-Endpunkt

Erstellen Sie einen HTTP v2-Endpunkt, der mit dem Token-Endpunkt des Anbieters verbunden ist:

1. Klicken Sie im -Tab Projektendpunkte und -verbinder der Design-Komponentenpalette auf HTTP v2, um eine neue Verbindung zu öffnen.

2. Verbindungsname: Geben Sie einen Namen ein (zum Beispiel Google OAuth).

3. Basis-URL: Geben Sie die Basis-URL des Token-Endpunkts des Anbieters ein (zum Beispiel https://oauth2.googleapis.com).

4. Autorisierung: Wählen Sie Keine Authentifizierung. Die Client-Anmeldeinformationen sind im Anforderungstext enthalten, nicht im Autorisierungsheader.

5. Klicken Sie auf Test, dann auf Änderungen speichern.

Schritt 3: Erstellen Sie die Exchange Token-Operation

Erstellen Sie eine neue Operation mit dem Namen Exchange Token. Diese Operation sendet den Autorisierungscode an den Token-Endpunkt und extrahiert die zurückgegebenen Tokens.

Skriptschritt (vor der POST-Aktivität)

Erstellen Sie den formatierten Anforderungstext:

<trans>
$tokenRequestBody = "code=" + URLEncode($authCode)
    + "&client_id=" + URLEncode($client_id)
    + "&client_secret=" + URLEncode($client_secret)
    + "&redirect_uri=" + URLEncode($redirect_uri)
    + "&grant_type=authorization_code";
</trans>

HTTP v2 POST-Aktivität

1. Ziehen Sie eine POST-Aktivität vom Google OAuth-Endpunkt auf die Operationsfläche.

2. Doppelklicken Sie auf die Aktivität, um deren Konfiguration zu öffnen.

3. Name: Geben Sie Exchange Token POST oder ähnliches ein.

4. Pfad: Geben Sie /token ein.

5. Anforderungsheader: Fügen Sie Content-Type / application/x-www-form-urlencoded hinzu.

6. Geben Sie im Schema-Schritt ein Anforderungsschema mit einem einzelnen Textfeld (zum Beispiel body) an, um den URL-kodierten String zu halten. Mappen Sie tokenRequestBody auf dieses Feld in der vorhergehenden Transformation.

7. Klicken Sie auf Fertig.

Skriptschritt (nach der POST-Aktivität)

Analysieren Sie die JSON-Antwort und extrahieren Sie die Tokens:

<trans>
$refresh_token = TrimChars(GetJSONString($jitterbit.response, "/refresh_token"), "\"");
$access_token = TrimChars(GetJSONString($jitterbit.response, "/access_token"), "\"");
RunOperation("<TAG>Operations/Store Refresh Token</TAG>");
</trans>

$jitterbit.response enthält den Rohantworttext aus der POST-Aktivität. GetJSONString extrahiert einzelne Felder nach JSON-Pfad. TrimChars entfernt die umgebenden Anführungszeichen, die GetJSONString in seiner Ausgabe enthält.

Schritt 4: Speichern Sie das Refresh-Token

Erstellen Sie eine neue Operation mit dem Namen Store Refresh Token. Verwenden Sie die Cloud Datastore-Aktivitäten Elemente einfügen und Elemente aktualisieren mit dem Muster Abfragen-dann-Zweigen, um das Refresh-Token zu speichern, das durch eine eindeutige Benutzerkennung (zum Beispiel die E-Mail-Adresse des Benutzers oder die Slack-Benutzer-ID) gekennzeichnet ist. Mappen Sie refresh_token auf das Refresh-Token-Feld im Cloud Datastore-Speicher.

Siehe Speichern und Abrufen des Sitzungsstatus mit Cloud Datastore für das vollständige Muster zum Abfragen, Einfügen und Aktualisieren.

Teil 5: Aktualisieren Sie das Zugriffstoken bei nachfolgenden Ausführungen

Nach der ersten Autorisierung kann das gespeicherte Refresh-Token ohne Benutzerinteraktion gegen ein neues Zugriffstoken eingetauscht werden. Eine Check Auth-Operation übernimmt dies und sollte zu Beginn jeder Operationenkette ausgeführt werden, die die Ziel-API aufruft.

Erstellen Sie die Check Auth-Operation

Erstellen Sie eine neue Operation mit dem Namen Check Auth. Fügen Sie einen Skript-Schritt mit hinzu:

<trans>
RunOperation("<TAG>Operations/Query Token</TAG>");
If(length(trim($refresh_token)) == 0,
    RaiseError("No refresh token found. Run the Connect operation to authorize access.")
);
RunOperation("<TAG>Operations/Refresh Access Token</TAG>");
</trans>

Die Query Token-Operation liest das gespeicherte Refresh-Token aus dem Cloud Datastore in refresh_token (unter Verwendung des gleichen Abfrage-nach-Schlüssel-Musters, das in Speichern und Abrufen des Sitzungsstatus mit Cloud Datastore beschrieben ist). Wenn kein Token gefunden wird, stoppt RaiseError die Kette, bevor ein API-Aufruf versucht wird.

Erstellen Sie die Refresh Access Token-Operation

Erstellen Sie eine neue Operation mit dem Namen Refresh Access Token. Fügen Sie einen Skript-Schritt gefolgt von einer HTTP v2 POST-Aktivität hinzu.

Skript-Schritt

<trans>
$tokenRequestBody = "refresh_token=" + URLEncode($refresh_token)
    + "&client_id=" + URLEncode($client_id)
    + "&client_secret=" + URLEncode($client_secret)
    + "&grant_type=refresh_token";
</trans>

HTTP v2 POST-Aktivität: Verwenden Sie die gleiche Google OAuth-Verbindung, die in Teil 4 erstellt wurde. Setzen Sie den Pfad auf /token und fügen Sie den Header Content-Type: application/x-www-form-urlencoded hinzu. Mappen Sie tokenRequestBody auf den Anfragekörper in der upstream-Transformation.

Skript-Schritt (nach der POST-Aktivität)

<trans>
$access_token = TrimChars(GetJSONString($jitterbit.response, "/access_token"), "\"");
</trans>

Die Variable access_token ist jetzt für jede nachfolgende Operation in der Kette verfügbar. Übergeben Sie sie als Bearer-Token im Authorization-Header von ausgehenden API-Anfragen:

<trans>
$jitterbit.api.request.headers.Authorization = "Bearer " + $access_token;
</trans>

Integration überprüfen

1. Projekt bereitstellen.

2. Führen Sie die Connect-Operation aus und öffnen Sie die Autorisierungs-URL, die sie in einem Browser erzeugt.

3. Folgen Sie dem OAuth-Zustimmungsfluss im Browser. Nach der Genehmigung des Zugriffs sollte der Browser die HTML-Bestätigungsseite anzeigen, die von der OAuth Callback-Operation bereitgestellt wird.

4. Öffnen Sie in Management Console > Cloud Datastore den Schlüssel-Speicher und bestätigen Sie, dass ein Datensatz mit der erwarteten Benutzerkennung und einem nicht leeren Refresh-Token-Feld erstellt wurde.

5. Führen Sie die Check Auth-Operation manuell aus. Bestätigen Sie im Betriebsprotokoll, dass die Refresh Access Token-Operation abgeschlossen wurde und dass access_token nicht leer ist.

6. Wenn der Browser eine Fehlerseite vom Anbieter anzeigt, anstatt der Bestätigungsseite:

   • Bestätigen Sie, dass die Projektvariable redirect_uri genau mit der URI übereinstimmt, die in der Anbieter-Konsole registriert ist, einschließlich Schema, Host und Pfad. OAuth-Anbieter lehnen jede Abweichung ab.
   • Überprüfen Sie die API-Protokolle im API-Manager, um zu bestätigen, dass die Callback-Anfrage den Endpunkt erreicht hat.

7. Wenn die Exchange Token-Operation mit einer 400- oder 401-Antwort fehlschlägt:

   • Bestätigen Sie, dass client_id und client_secret korrekt gesetzt sind.
   • Bestätigen Sie, dass authCode nicht bereits verwendet wurde. Autorisierungscodes sind nur einmal verwendbar und laufen nach kurzer Zeit (typischerweise 10 Minuten) ab.

8. Wenn die Refresh Access Token-Operation mit einer 401-Antwort fehlschlägt, könnte das gespeicherte Refresh-Token ungültig oder widerrufen worden sein. Führen Sie die Connect-Operation für diesen Benutzer erneut aus, um ein neues Refresh-Token zu erhalten und den gespeicherten Wert zu aktualisieren.