API-Endpunkte in Jitterbit Studio mit JWT authentifizieren

Einführung

API Manager-Endpunkte akzeptieren Anfragen von jedem Aufrufer, der die URL kennt. Um den Zugriff einzuschränken, können Sie verlangen, dass Aufrufer sich mit einem signierten JSON Web Token (JWT) authentifizieren: ein kompaktes, URL-sicheres Token, das die Identität des Aufrufers und eine Ablaufzeit codiert.

Diese Anleitung behandelt den vollständigen Authentifizierungszyklus mit dem JWT-Connector:

• Eine Login-Operation akzeptiert eine Aufruferidentität, generiert einen signierten JWT und gibt ihn an den Aufrufer zurück.
• Geschützte Operationen validieren das Token bei jeder Anfrage, bevor die Verarbeitung beginnt.

Der JWT-Connector verarbeitet die Token-Generierung und -Validierung lokal. Er verbindet sich nicht mit einem externen Service.

Diese Anleitung setzt Folgendes voraus:

• Eine benutzerdefinierte API ist in API Manager in derselben Umgebung wie das Projekt konfiguriert und veröffentlicht.
• Sie sind mit dem Erstellen von benutzerdefinierten API-Endpunkten in API Manager vertraut.

Teil 1: JWT-Verbindung erstellen

Eine JWT-Verbindung ist ein benannter Endpunkt, der Ihnen Zugriff auf die Aktivitätstypen Token generieren, Token dekodieren und Token validieren gibt.

1. Öffnen Sie in Studio die Design-Komponentenpalette und wählen Sie die Registerkarte Projektendpunkte und Connectors aus.

2. Suchen Sie den JWT-Connector und konfigurieren Sie eine neue Verbindung.

3. Verbindungsname: Geben Sie einen Namen ein (z. B. JWT).

4. Klicken Sie auf Änderungen speichern.

Der JWT-Endpunkt wird in der Registerkarte Projektendpunkte und Connectors angezeigt. Weitere Informationen finden Sie unter JWT-Verbindung.

Teil 2: Login-Endpunkt erstellen

Der Login-Endpunkt akzeptiert eine POST-Anfrage und gibt einen signierten JWT zurück. Aufrufer präsentieren dieses Token im Authorization-Header aller nachfolgenden Anfragen an geschützte Endpunkte.

Schritt 1: Signierschlüssel speichern

Sowohl die Aktivität Token generieren als auch die Aktivität Token validieren verwenden denselben Signierschlüssel. Speichern Sie ihn als Projektvariable, damit sein Wert nicht hartcodiert ist und nicht in Operationsprotokollen angezeigt wird. Die vollständigen Schritte und Best Practices für die Verwaltung von Anmeldedaten als verborgene Projektvariablen finden Sie unter Endpunkt-Anmeldedaten verwalten.

1. Öffnen Sie in Studio das Projektaktionsmenü und wählen Sie Projektvariablen aus.

2. Fügen Sie eine Variable namens jwt.secret hinzu und geben Sie eine starke, zufällig generierte Zeichenkette als Wert ein.

3. Aktivieren Sie Wert ausblenden.

4. Klicken Sie auf Speichern.

Schritt 2: Aktivität „Token generieren" konfigurieren

1. Erweitern Sie in der Design-Komponentenpalette den JWT-Endpunkt und ziehen Sie den Aktivitätstyp Token generieren auf die Design-Canvas.

2. Name: Geben Sie einen Namen ein (z. B. Generate Login Token).

3. JWT-Typ: Wählen Sie JWS aus.

4. Signaturtyp: Wählen Sie Symmetric aus.

5. Signaturalgorithmen: Wählen Sie HS256 aus.

6. Geheimer Schlüssel: Geben Sie [jwt.secret] ein.

7. Erweitern Sie Optionale Einstellungen und fügen Sie die folgenden Payload-Eigenschaften hinzu. Diese verweisen auf Projektvariablen, die das Login-Operationsskript zur Laufzeit setzt:

   Schlüssel	Wert	Datentyp
   sub	[jwt.sub]	string
   iat	[jwt.iat]	number
   exp	[jwt.exp]	number

8. Klicken Sie auf Fertig.

Beschreibungen aller Aktivitätseinstellungen finden Sie unter JWT-Aktivität „Token generieren".

Schritt 3: API-Endpunkt für Login erstellen

1. Klicken Sie in API Manager auf Neue API und wählen Sie Benutzerdefinierte API aus.

2. Geben Sie einen API-Namen (z. B. Auth API), ein URL-Präfix (z. B. auth) und eine Versionsnummer ein.

3. SSL aktivieren.

4. Klicken Sie auf Speichern und dann auf Service hinzufügen.

5. Methode: Wählen Sie POST aus.

6. Pfad: Geben Sie /token ein.

7. Operation: Wählen Sie die Login-Operation aus. Falls die Operation noch nicht vorhanden ist, erstellen Sie einen Platzhalter und kehren Sie zurück, um dieses Feld nach Abschluss von Schritt 4 zu aktualisieren.

8. Antworttyp: Wählen Sie Systemvariable aus.

9. Klicken Sie auf Speichern und dann auf Veröffentlichen.

Schritt 4: Login-Operation erstellen

Die Login-Operation besteht aus einem Vorbereitungsskript und einer Transformation, die die Aktivität Token generieren ausführt.

1. Erstellen Sie die Projektvariablen für Token-Ansprüche, indem Sie diese in der Schublade Projektvariablen neben jwt.secret hinzufügen:

   Name	Beschreibung
   jwt.sub	Die Identität des Aufrufers (Subject Claim)
   jwt.iat	Ausstellungszeit als Unix-Epoch-Zeitstempel
   jwt.exp	Ablaufzeit als Unix-Epoch-Zeitstempel

2. Fügen Sie ein Vorbereitungsskript als ersten Schritt der Login-Operation hinzu. Dieses Skript liest die Identität des Aufrufers aus dem Request-Body und setzt die Claim-Projektvariablen:

   <trans>
   $body = JSONParser($jitterbit.api.request.body);
   
   // Set the subject claim from the request body
   $jwt.sub = Get($body, "userId");
   
   // Set the issue time and expiry as Unix epoch timestamps
   // (seconds since 1970-01-01 00:00:00 UTC)
   $jwt.iat = Long(Now());
   $jwt.exp = $jwt.iat + 3600;  // 1-hour token lifetime
   </trans>
   

   Long(Now()) konvertiert das aktuelle Datum und die aktuelle Uhrzeit in eine Unix-Epoch-Ganzzahl (Sekunden seit 1970-01-01 00:00:00 UTC). Passen Sie den Ablauf-Offset (3600) an die von Ihrer Sicherheitsrichtlinie erforderliche Token-Lebensdauer an.

3. Fügen Sie einen Transformationsschritt nach dem Vorbereitungsskript hinzu, wobei die Aktivität Token generieren das Ziel ist. Ordnen Sie in der Transformation jede Claim-Projektvariable dem entsprechenden Payload-Schemaknoten zu. Die Aktivität Token generieren liest die Claim-Werte aus [jwt.sub], [jwt.iat] und [jwt.exp] und schreibt das signierte JWT in sein Ausgabeschema.

4. Legen Sie die API-Antwort fest, indem Sie einen zweiten Transformationsschritt hinzufügen (unter Verwendung des Zwei-Transformations-Operationsmuster), um das generierte Token aus der Ausgabe der Aktivität auf $jitterbit.api.response abzubilden. Die Aktivität Token generieren schreibt das signierte JWT in sein Ausgabedatenschema, das in Schritt 2: Datenschemas überprüfen der Aktivitätskonfiguration angezeigt wird:

   <trans>
   $token_response = Dict();
   $token_response["token"] = $jwt_generated_token;
   $jitterbit.api.response = JSONStringify($token_response);
   $jitterbit.api.response.status_code = 200;
   </trans>
   

   Ersetzen Sie $jwt_generated_token durch die Variable oder den Pfad, der aus dem Ausgabeschema der Aktivität Token generieren zugeordnet wird. Der genaue Feldname wird im Datenschema-Überprüfungsschritt der Aktivitätskonfiguration angezeigt.

Teil 3: Token auf geschützten Endpunkten validieren

Jede geschützte Operation muss das JWT des Aufrufers vor der Verarbeitung der Anfrage überprüfen. Fügen Sie eine Validierungsoperation hinzu, die vor der geschützten Operation ausgeführt wird und eine 401-Antwort zurückgibt, wenn das Token fehlt oder ungültig ist.

Schritt 1: Aktivität „Token validieren" konfigurieren

1. Erweitern Sie in der Designkomponentenpalette den Endpunkt JWT und ziehen Sie den Aktivitätstyp Token validieren auf die Designoberfläche.

2. Name: Geben Sie einen Namen ein (z. B. Login-Token validieren).

3. JWT-Token: Geben Sie [jwt.incoming_token] ein. Dies verweist auf eine Projektvariable, die das Validierungsskript aus dem Header Authorization setzt.

4. JWT-Typ: Wählen Sie JWS aus.

5. Geheimer Schlüssel: Geben Sie [jwt.secret] ein.

6. Klicken Sie auf Fertig.

Beschreibungen aller Aktivitätseinstellungen finden Sie unter JWT-Aktivität „Token validieren".

Fügen Sie eine Projektvariable namens jwt.incoming_token in der Schublade Projektvariablen hinzu.

Schritt 2: Validierungsoperation erstellen

Erstellen Sie eine neue Skriptoperation, die als Gateway für Ihren geschützten Endpunkt fungiert. Diese Operation extrahiert das Token, führt die Aktivität Token validieren aus und übergibt die Kontrolle an die geschützte Operation, wenn die Validierung erfolgreich ist.

1. Fügen Sie ein Extraktionsskript als ersten Schritt der Validierungsoperation hinzu. Dieses Skript liest den Header Authorization, prüft auf das Präfix Bearer und setzt jwt.incoming_token:

   <trans>
   $auth_header = $jitterbit.api.request.headers.Authorization;
   
   If(Left($auth_header, 7) != "Bearer ",
     $jitterbit.api.response.status_code = 401;
     $err_response = Dict();
     $err_response["error"] = "Missing or malformed Authorization header";
     $jitterbit.api.response = JSONStringify($err_response);
     RaiseError("Unauthorized");
   );
   
   $jwt.incoming_token = Mid($auth_header, 8);
   </trans>
   

   Left prüft die ersten sieben Zeichen des Headers. Mid extrahiert alles nach dem Präfix Bearer. RaiseError stoppt die Operation sofort und löst die konfigurierte Fehleraktion aus.

2. Fügen Sie eine Validierungstransformation mit der Aktivität Validate Token als Ziel hinzu. Die Aktivität liest das Token aus [jwt.incoming_token] und überprüft seine Signatur gegen [jwt.secret]. Wenn das Token ungültig, abgelaufen oder manipuliert wurde, löst die Aktivität einen Fehler aus.

Schritt 3: Fehler- und Erfolgsaktionen für den Validierungsvorgang konfigurieren

Öffnen Sie die Einstellungen des Validierungsvorgangs und wählen Sie die Registerkarte Aktionen.

Bei Fehler (ungültiges Token):

1. Bedingung: Wählen Sie On Fail.
2. Aktion: Wählen Sie Run Operation.

3. Vorgang: Wählen Sie einen Skriptvorgang aus oder erstellen Sie einen, der eine 401-Antwort zurückgibt:

   <trans>
   $jitterbit.api.response.status_code = 401;
   $err_response = Dict();
   $err_response["error"] = "Invalid or expired token";
   $jitterbit.api.response = JSONStringify($err_response);
   </trans>
   

4. Klicken Sie auf Add Action.

Bei Erfolg (gültiges Token):

1. Bedingung: Wählen Sie On Success.
2. Aktion: Wählen Sie Run Operation.
3. Vorgang: Wählen Sie den geschützten Vorgang aus.
4. Klicken Sie auf Add Action.

Speichern Sie die Einstellungen. Der Validierungsvorgang fungiert nun als Gateway: Wenn das Token gültig ist, wird es an den geschützten Vorgang weitergeleitet; wenn es ungültig oder fehlend ist, wird eine 401-Antwort zurückgegeben und der Vorgang beendet.

Aktualisieren Sie in API Manager das Feld Operation des geschützten Endpunkts so, dass es auf den Validierungsvorgang statt direkt auf den geschützten Vorgang verweist. Der Validierungsvorgang wird bei Erfolg an den geschützten Vorgang weitergeleitet.

Integration überprüfen

1. Stellen Sie das Projekt bereit und bestätigen Sie, dass sowohl der Login-Endpunkt als auch der geschützte Endpunkt in API Manager veröffentlicht sind.

2. Senden Sie eine POST-Anfrage an den Endpunkt /auth/token mit einem JSON-Text, der ein Feld userId enthält:

   {"userId": "user123"}
   

   Bestätigen Sie, dass der Antwortkörper ein Feld token enthält.

3. Senden Sie eine Anfrage an den geschützten Endpunkt mit dem Token im Header Authorization:

   Authorization: Bearer <token>
   

   Bestätigen Sie, dass der Vorgang erfolgreich abgeschlossen wird.

4. Senden Sie eine Anfrage an den geschützten Endpunkt ohne einen Header Authorization. Bestätigen Sie, dass der Endpunkt eine 401-Antwort zurückgibt.

5. Ändern Sie die Token-Zeichenfolge (ändern Sie beispielsweise das letzte Zeichen) und senden Sie sie. Bestätigen Sie, dass der Endpunkt eine 401-Antwort zurückgibt.

6. Wenn ein Schritt fehlschlägt, öffnen Sie die Vorgangsprotokolle in Studio, um auf Fehler zu prüfen.