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

Einführung

Der OAuth 2.0-Autorisierungscode-Flow ermöglicht es einer Studio-Operation, im Namen eines bestimmten Benutzers auf eine API eines Drittanbieters zuzugreifen, wobei die delegierten Anmeldedaten des Benutzers anstelle eines gemeinsamen Dienstkontos 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. Das gleiche Muster gilt für jeden OAuth 2.0-Anbieter, der den Autorisierungscode-Grant-Typ unterstützt: Ersetzen Sie die anbieterspezifischen URLs, Bereiche und Parameternamen durch die Werte für den Zieldienst.

Verwenden Sie dieses Muster, wenn:

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

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

Diese Anleitung setzt Folgendes voraus:

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

Designmuster

Drei Operationen implementieren den OAuth 2.0-Autorisierungscode-Flow:

Die Connect-Operation konstruiert die Autorisierungs-URL und übermittelt sie an den Benutzer. Die OAuth Callback-Operation 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. Die Check Auth-Operation wird vor jedem API-Aufruf ausgeführt: Sie liest das gespeicherte Aktualisierungstoken aus Cloud Datastore und tauscht es gegen ein neues Zugriffstoken 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 resultierenden Anmeldedaten als Projektvariablen.

Anwendung registrieren

Erstellen Sie in der Entwicklerkonsole Ihres OAuth-Anbieters (z. B. Google Cloud Console) eine OAuth 2.0-Berechtigung vom Typ Web application und konfigurieren Sie:

• Authorized 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 Secret aus.

Anmeldedaten als Projektvariablen speichern

Öffnen Sie in Studio das Projektaktionsmenü 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-Secret.
• redirect_uri: Die vollständige Callback-URL, die in der Anbieterkonsole konfiguriert ist.

Referenzieren Sie 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, bevor Sie Scripts schreiben, 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. Nennen Sie sie OAuth Callback oder einen ähnlichen Namen.

2. Fügen Sie einen Script-Schritt als ersten Schritt hinzu. Lassen Sie den Script-Body vorerst leer. Sie fügen die Callback-Logik 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 beim Konfigurieren des Endpunkts Folgendes fest:

• Method: GET. OAuth-Provider leiten den Browser des Benutzers mit einem GET-Request mit Abfrageparametern zur Callback-URL um.
• Path: /oauth/callback (oder ein beliebiger Pfad, der dem Redirect-URI entspricht, den Sie beim Provider registrieren).
• Response Type: System Variable. Das Callback-Script 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 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 stellt sie dem Benutzer zur Verfügung.

Connect-Operation erstellen

Erstellen Sie eine neue Operation. Nennen Sie sie Connect oder einen ähnlichen Namen. Fügen Sie einen Script-Schritt mit folgendem Script 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-codieren Sie die kombinierte Zeichenkette mit URLEncode. Passen Sie die Scope-Werte an die Anforderungen Ihrer Ziel-API an.
• access_type=offline: Weist den Provider an, zusätzlich zum Access-Token ein Refresh-Token auszugeben.
• prompt=consent: Erzwingt die Anzeige des Zustimmungsbildschirms, auch wenn der Benutzer die Anwendung bereits autorisiert hat. Dies stellt sicher, dass jedes Mal ein neues Refresh-Token ausgestellt wird.

Ersetzen Sie die Google-Autorisierungs-Endpunkt-URL und die Scope-Werte durch die für Ihren Ziel-Provider.

URL an den Benutzer übermitteln

Nach der Erstellung der URL stellen Sie sie bereit, damit der Benutzer sie in einem Browser öffnen kann. Um die URL als Slack-Ephemeral-Nachricht zu senden (z. B. in einem Agent, der Slack als Schnittstelle verwendet):

<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-Body einbinden.

Teil 4: Callback verarbeiten und Autorisierungscode austauschen

Die OAuth Callback-Operation wird ausgeführt, wenn der Provider den Browser des Benutzers zur registrierten Callback-URL umleitet. Sie muss den Autorisierungscode extrahieren, eine HTML-Bestätigungsseite im Browser bereitstellen, den Code gegen Tokens austauschen und das 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. Der Response-Body, der Content-Type und der Statuscode, 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: Konfigurieren Sie die Token-Endpunkt-Verbindung

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

1. Klicken Sie auf der Registerkarte Projektendpunkte 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-Endpunkts des Anbieters ein (z. B. https://oauth2.googleapis.com).

4. Autorisierung: 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: Erstellen Sie den Exchange Token-Vorgang

Erstellen Sie einen neuen Vorgang namens Exchange Token. Dieser Vorgang sendet den Autorisierungscode an den Token-Endpunkt 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-Endpunkt auf die Operationsleinwand.

2. Doppelklicken Sie auf die Aktivität, um ihre 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. Geben Sie im Schema-Schritt ein Request-Schema mit einem einzelnen Textfeld (z. B. body) an, um die URL-codierte Zeichenkette zu speichern. Ordnen Sie in der vorgelagerten Transformation 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 seiner Ausgabe enthält.

Schritt 4: Speichern Sie das Refresh-Token

Erstellen Sie einen neuen Vorgang namens Store Refresh Token. Verwenden Sie Cloud Datastore-Aktivitäten Elemente einfügen und Elemente aktualisieren mit dem Query-then-Branch-Muster, um das Refresh-Token mit einem eindeutigen Benutzeridentifikator (z. B. der E-Mail-Adresse oder Slack-Benutzer-ID des Benutzers) zu speichern. Ordnen Sie refresh_token dem Refresh-Token-Feld im Cloud Datastore-Speicher zu.

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

Teil 5: Aktualisieren Sie das Access-Token bei nachfolgenden Ausführungen

Nach der anfänglichen Autorisierung kann das gespeicherte Refresh-Token gegen ein neues Access-Token ausgetauscht werden, ohne dass eine Benutzerinteraktion erforderlich ist. Ein Check Auth-Vorgang verwaltet dies und sollte am Anfang jeder Operationskette ausgeführt werden, die die Ziel-API aufruft.

Erstellen Sie den Check Auth-Vorgang

Erstellen Sie einen neuen Vorgang namens Check Auth. Fügen Sie einen Script-Schritt mit folgendem Inhalt 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>

Der Query Token-Vorgang liest das gespeicherte Refresh-Token aus Cloud Datastore in refresh_token (mit dem gleichen Query-by-Key-Muster, das in Sitzungsstatus mit Cloud Datastore speichern und abrufen beschrieben ist). Wenn kein Token gefunden wird, stoppt RaiseError die Kette, bevor ein API-Aufruf versucht wird.

Erstellen Sie den Refresh Access Token-Vorgang

Erstellen Sie einen neuen Vorgang namens 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 dieselbe Google OAuth-Verbindung, die in Teil 4 erstellt wurde. Legen Sie den Pfad auf /token fest 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 steht nun für alle nachfolgenden Operationen in der Kette zur Verfügung. Übergeben Sie sie als Bearer-Token im Header Authorization von ausgehenden 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 generierte 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 Benutzerkennung und einem nicht leeren Feld für das Aktualisierungs-Token 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 exakt mit dem URI übereinstimmt, der in der Provider-Konsole registriert ist, einschließlich Schema, Host und Pfad. OAuth-Provider 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 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 noch nicht verwendet wurde. Autorisierungscodes sind einmalig verwendbar und verfallen nach kurzer Zeit (typischerweise 10 Minuten).

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