OAuth 2.0-Autorisierungscode-Flow mit Token-Speicherung in Jitterbit Studio implementieren

Einführung

Der OAuth 2.0-Autorisierungscode-Flow ermöglicht es einem Studio-Vorgang, im Namen eines bestimmten Benutzers auf eine API eines Drittanbieters zuzugreifen, indem die delegierten Anmeldedaten dieses Benutzers statt eines gemeinsamen Service-Kontos verwendet werden. Diese Anleitung behandelt den vollständigen Flow: Konstruktion der Autorisierungs-URL, Empfang des Autorisierungscodes an einem Callback-Endpunkt, Austausch des Codes gegen Zugriffs- und Aktualisierungstoken, Speicherung des Aktualisierungstokens in Cloud Datastore und Aktualisierung des Zugriffstokens bei nachfolgenden Ausführungen ohne Benutzerinteraktion.

Die Beispiele in dieser Anleitung verwenden Google als Autorisierungsanbieter. Dasselbe Muster gilt für jeden OAuth 2.0-Anbieter, der den Autorisierungscode-Grant-Typ unterstützt: Ersetzen Sie die anbieterspezifischen URLs, Scopes und Parameternamen durch die Werte für den Zieldienst.

Verwenden Sie dieses Muster, wenn:

• Die Ziel-API Berechtigungen auf Benutzerebene erfordert, die ein Service-Konto nicht bieten kann.
• Sie langfristigen Zugriff mit Aktualisierungstoken benötigen, ohne wiederholte manuelle Autorisierung.
• Sie einen KI-Agenten oder automatisierten Workflow entwickeln, der auf Benutzer-Mailboxen, Kalender oder Dokumente zugreift.

Für APIs, die API-Schlüssel oder Client-Anmeldedaten statt Benutzerautorisierung verwenden, siehe Endpunkt-Anmeldedaten verwalten und REST-API mit dem HTTP v2-Connector aufrufen.

Diese Anleitung geht davon aus:

• Eine benutzerdefinierte API ist in API Manager in der gleichen Umgebung wie das Projekt konfiguriert und veröffentlicht.
• Ein Cloud Datastore-Schlüsselspeicher vorhanden ist oder erstellt wird, um Pro-Benutzer-Token-Datensätze zu speichern. Siehe Sitzungszustand mit Cloud Datastore speichern und abrufen für Einrichtungsschritte.
• Das Projekt hat eine Möglichkeit, eine URL an den Benutzer zu übermitteln, wie eine Slack-Nachricht oder eine App Builder-Schnittstelle.

Entwurfsmuster

Drei Vorgänge implementieren den OAuth 2.0-Autorisierungscode-Flow:

Der Connect-Vorgang erstellt die Autorisierungs-URL und übermittelt sie an den Benutzer. Der OAuth Callback-Vorgang empfängt den Autorisierungscode, wenn der Anbieter den Browser des Benutzers umleitet, tauscht den Code gegen Token aus und speichert das Aktualisierungstoken zur zukünftigen Verwendung. Der Check Auth-Vorgang wird vor jedem API-Aufruf ausgeführt: Er liest das gespeicherte Aktualisierungstoken aus Cloud Datastore und tauscht es gegen einen neuen Zugriffscode aus.

Teil 1: OAuth-Anwendung registrieren und Anmeldedaten speichern

Bevor Sie Scripts schreiben, registrieren Sie Studio als OAuth-Anwendung beim Autorisierungsanbieter und speichern Sie die erhaltenen Anmeldedaten als Projektvariablen.

Anwendung registrieren

In der Entwicklerkonsole Ihres OAuth-Anbieters (z. B. Google Cloud Console) erstellen Sie eine OAuth 2.0-Anmeldedaten vom Typ Webanwendung und konfigurieren:

• Autorisierte Redirect-URIs: Fügen Sie die vollständige URL des Callback-Endpunkts hinzu, den Sie in Teil 2 erstellen. 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.

Anmeldedaten als Projektvariablen speichern

Öffnen Sie in Studio das Projektmenü und wählen Sie Projektvariablen. Erstellen Sie die folgenden Projektvariablen mit ausgeblendeten Werten:

• client_id: Die OAuth-Anwendungs-Client-ID, die vom Anbieter ausgestellt wurde.
• client_secret: Das OAuth-Anwendungs-Client-Geheimnis.
• redirect_uri: Die vollständige Callback-URL, die in der Anbieterkonsole konfiguriert ist.

Verweisen Sie auf diese Variablen in Scripts mit dem $-Präfix (z. B. $client_id, $client_secret, $redirect_uri).

Teil 2: Callback-Endpunkt erstellen

Der Callback-Endpunkt empfängt den Autorisierungscode vom Provider, nachdem der Benutzer den Zugriff genehmigt hat. Erstellen Sie ihn vor dem Schreiben von Skripten, damit die vollständige URL zur Konfiguration in der Provider-Konsole verfügbar ist.

Callback-Operation erstellen

1. Erstellen Sie in Studio eine neue Operation. Geben Sie ihr den Namen OAuth Callback oder einen ähnlichen Namen.

2. Fügen Sie einen Script-Schritt als ersten Schritt hinzu. Lassen Sie den Skripttext vorerst leer. Die Callback-Logik fügen Sie in Teil 4 hinzu.

Callback-Operation als API-Endpunkt veröffentlichen

Folgen Sie Studio-Operation als REST-API verfügbar machen, um die OAuth Callback-Operation zu veröffentlichen. Legen Sie bei der Konfiguration des Endpunkts fest:

• Methode: GET. OAuth-Provider leiten den Browser des Benutzers mit einem GET-Request mit Abfrageparametern an die Callback-URL weiter.
• Pfad: /oauth/callback (oder ein beliebiger Pfad, der dem Redirect-URI entspricht, den Sie beim Provider registrieren werden).
• Antworttyp: System Variable. Das Callback-Skript setzt $jitterbit.api.response.body und $jitterbit.api.response.headers.Content_Type, um eine HTML-Bestätigungsseite bereitzustellen.

Kopieren Sie die URL des veröffentlichten Endpunkts. Verwenden Sie sie als Wert der redirect_uri-Projektvariable und registrieren Sie sie beim Provider als autorisierter Redirect-URI.

Teil 3: Autorisierungs-URL erstellen

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

Connect-Operation erstellen

Erstellen Sie eine neue Operation. Geben Sie ihr den Namen Connect oder einen ähnlichen Namen. Fügen Sie einen Script-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 durch Leerzeichen und kodieren Sie die kombinierte Zeichenkette mit URL-Kodierung mit URLEncode. Passen Sie die Scope-Werte an die Anforderungen Ihrer Ziel-API an.
• access_type=offline: Teilt dem Provider mit, einen Refresh-Token zusätzlich zum Access-Token auszustellen.
• prompt=consent: Erzwingt die Anzeige des Zustimmungsbildschirms, auch wenn der Benutzer die Anwendung bereits autorisiert hat. Dies stellt sicher, dass jedes Mal ein neuer Refresh-Token ausgegeben wird.

Ersetzen Sie die Google-Autorisierungs-Endpunkt-URL und die Scope-Werte durch die Werte Ihres Ziel-Providers.

URL an Benutzer liefern

Nach dem Erstellen der URL liefern Sie diese, damit der Benutzer sie in einem Browser öffnen kann. Um die URL als ephemere Slack-Nachricht zu senden (beispielsweise in einem Agent, der Slack als Schnittstelle nutzt):

<trans>
$jitterbit.api.response = "{\"response_type\": \"ephemeral\", \"text\": \"To connect your account, open this link: " + $authUrl + "\"}";
</trans>

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

Teil 4: Callback verarbeiten und Autorisierungscode austauschen

Die OAuth Callback-Operation wird ausgeführt, wenn der Provider den Browser des Benutzers an die registrierte Callback-URL umleitet. Sie muss den Autorisierungscode extrahieren, eine HTML-Bestätigungsseite im Browser bereitstellen, den Code gegen Token austauschen und den Refresh-Token speichern.

Schritt 1: Autorisierungscode extrahieren und Bestätigungsseite bereitstellen

Öffnen Sie in der OAuth Callback-Operation den Script-Schritt und fügen Sie Folgendes 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 Abfragezeichenkette der Redirect-URL. Textkörper, Inhaltstyp und Statuscode der Antwort, die hier gesetzt werden, werden an den Browser zurückgegeben, wenn die Operation abgeschlossen ist. RunOperation ruft die Exchange Token-Operation synchron auf: Der Token-Austausch findet statt, bevor die Antwort zurückgegeben wird, und die globale Variable authCode ist für die aufgerufene Operation verfügbar.

Schritt 2: Verbindung des Token-Endpoints konfigurieren

Erstellen Sie einen HTTP v2-Endpoint, der mit dem Token-Endpoint des Providers verbunden ist:

1. Klicken Sie in der Registerkarte Projekt-Endpoints und Konnektoren der Design-Komponentenpalette auf HTTP v2, um eine neue Verbindung zu öffnen.

2. Verbindungsname: Geben Sie einen Namen ein (z. B. Google OAuth).

3. Basis-URL: Geben Sie die Basis-URL des Token-Endpoints des Providers ein (z. B. https://oauth2.googleapis.com).

4. Authentifizierung: Wählen Sie Keine Authentifizierung. Die Client-Anmeldedaten sind im Request Body enthalten, nicht in einem Autorisierungs-Header.

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

Schritt 3: Token-Exchange-Operation erstellen

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

Script-Schritt (vor der POST-Aktivität)

Erstellen Sie den form-codierten Request Body:

<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-Endpoint auf die Operationsoberfläche.

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

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

4. Pfad: Geben Sie /token ein.

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

6. Im Schema-Schritt stellen Sie ein Request-Schema mit einem einzelnen Textfeld bereit (z. B. body), um die URL-codierte Zeichenkette zu enthalten. In der vorgelagerten Transformation ordnen Sie tokenRequestBody diesem Feld zu.

7. Klicken Sie auf Fertig.

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

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

<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 rohen Response Body der POST-Aktivität. GetJSONString extrahiert einzelne Felder nach JSON-Pfad. TrimChars entfernt die umschließenden Anführungszeichen, die GetJSONString in der Ausgabe enthält.

Schritt 4: Refresh-Token speichern

Erstellen Sie eine neue Operation mit dem Namen Store Refresh Token. Verwenden Sie Cloud Datastore-Aktivitäten Items einfügen und Items aktualisieren mit dem Query-then-Branch-Muster, um den Refresh-Token zu persistieren, der mit einer eindeutigen Benutzer-ID (z. B. der E-Mail-Adresse oder Slack-Benutzer-ID des Benutzers) gekennzeichnet ist. Ordnen Sie refresh_token dem Refresh-Token-Feld im Cloud Datastore-Speicher zu.

Siehe Sitzungszustand mit Cloud Datastore speichern und abrufen für das vollständige Query-Insert-Update-Muster.

Teil 5: Access-Token bei nachfolgenden Läufen aktualisieren

Nach der ersten Autorisierung kann der gespeicherte Refresh-Token gegen einen neuen Access-Token ausgetauscht werden, ohne dass eine Benutzerinteraktion erforderlich ist. Eine Check Auth-Operation führt dies durch und sollte zu Beginn jeder Operationskette ausgeführt werden, die die Ziel-API aufruft.

Check Auth-Operation erstellen

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

<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 den gespeicherten Refresh-Token von Cloud Datastore in refresh_token (mit dem gleichen in Sitzungszustand mit Cloud Datastore speichern und abrufen beschriebenen Query-by-Key-Muster). Falls kein Token gefunden wird, beendet RaiseError die Kette, bevor ein API-Aufruf versucht wird.

Refresh Access Token-Operation erstellen

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

Script-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. Ordnen Sie tokenRequestBody dem Request-Body in der vorgelagerten Transformation zu.

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

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

Die Variable access_token ist nun für alle nachfolgenden Operationen in der Kette verfügbar. Übergeben Sie sie als Bearer-Token im Header Authorization ausgehender API-Anfragen:

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

Integration überprüfen

1. Stellen Sie das Projekt bereit.

2. Führen Sie die Operation Connect aus und öffnen Sie die von ihr erzeugte Autorisierungs-URL in einem Browser.

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

4. Öffnen Sie in Management Console > Cloud Datastore den Schlüsselspeicher und bestätigen Sie, dass ein Datensatz mit der erwarteten Benutzer-ID und einem nicht leeren Feld für das Aktualisierungstoken erstellt wurde.

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

6. Wenn der Browser statt der Bestätigungsseite eine Fehlerseite des Providers anzeigt:

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

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

   • Bestätigen Sie, dass client_id und client_secret korrekt eingestellt sind.
   • Bestätigen Sie, dass authCode nicht bereits verwendet wurde. Autorisierungscodes sind einmalig verwendbar und verfallen nach kurzer Zeit (üblicherweise 10 Minuten).

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