Installieren eines Jitterbit privaten API-Gateways auf Linux

Übersicht

Diese Seite erklärt, wie man ein privates API-Gateway installiert, konfiguriert und testet.

Systemanforderungen

Dieser Abschnitt gibt die Mindestanforderungen für einen API-Gateway-Host an.

Hardware

Betriebssysteme

Netzwerk

• Ein Sub-Domain oder Domain-Name, der auf den Server zeigt (zum Beispiel mysubdomain.example.com).

• Ein gültiges SSL-Zertifikat für die Sub-Domain, von einer anerkannten Zertifizierungsstelle; verwenden Sie kein selbstsigniertes Zertifikat.

  Das Zertifikat sollte aus zwei Dateien bestehen: einer CRT-Datei (.crt) für das signierte Zertifikat und einer KEY-Datei (.key) für den privaten Schlüssel. Diese sollten im PEM-Format vorliegen, das ein NGINX-Server verstehen kann. (Manchmal sind die Dateiendungen unterschiedlich; oft sind die Endungen CRT, PEM und CER austauschbar.) Es ist auch möglich, dass die beiden Dateien in einer einzigen PFX-Datei kombiniert sind. In diesem Fall verwenden Sie OpenSSL, um die beiden Dateien zu extrahieren.

  Hinweis

  Kostenlose SSL-Zertifikate sind von Anbietern wie Let's Encrypt erhältlich.

• SSH-Konnektivität.

Konten

Ihr Harmony muss über eine Rolle mit Admin-Berechtigung verfügen. (Agent Install-Berechtigung allein reicht nicht aus.)

Empfehlungen

Bei der Einrichtung Ihres API-Gateway-Hosts sollten Sie die empfohlenen Punkte beachten:

• Teilen Sie den Host nicht mit anderen Nicht-Systemanwendungen.

• Konfigurieren Sie den Host für optimale Leistung.

• Installieren Sie die folgenden zusätzlichen Pakete für Ihren Hosttyp:

  • Red Hat Enterprise Linux (RHEL): Wenn cloudbasiert, verwenden Sie einen Compute-Knoten mit den folgenden Paketgruppen:

    • Debugging-Tools.
    • Hardware-Überwachungs-Utilities.
    • Kompatibilitätsbibliotheken.
    • Entwicklungstools.
    • Sicherheitstools.

  • Debian, Ubuntu: Verwenden Sie eine Standardinstallation und wählen Sie die folgenden zusätzlichen Pakete aus:

    • OpenSSH.

• Netzwerk: Öffnen Sie den Port 443 (HTTPS). Sie können die folgenden Befehle verwenden, um dies zu tun:

  Red Hat, Amazon LinuxDebian, Ubuntu

  firewall-cmd --zone=public --add-port=443/tcp --permanent
  firewall-cmd --reload
  

  ufw allow 443/tcp
  

Installieren und Konfigurieren eines privaten API-Gateways

Um ein privates API-Gateway zu installieren und zu konfigurieren, befolgen Sie diese Schritte mit einem Konto mit Root-Rechten:

1. Laden Sie eines der folgenden Softwarepakete für private API-Gateways von der Harmony-Portal-Seite Downloads herunter und kopieren Sie es auf Ihren API-Gateway-Host:

   • Linux RPM: Die .rpm-Paketdatei zur Installation auf Red Hat oder Amazon Linux.

   • Linux Debian: Die .deb-Paketdatei zur Installation auf Debian oder Ubuntu Linux.

2. Führen Sie diese Befehle für Ihre Kombination aus Betriebssystem und Gateway-Version aus, wobei Sie x.x.x.x (.deb) oder x.x.x-x (.rpm) durch die heruntergeladene Versionsnummer ersetzen:

   Red Hat, Amazon LinuxDebian, UbuntuUbuntu 24.04 LTS

   API-Gateway 10.61 oder früherAPI-Gateway 10.62 oder später

   yum update
   yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
   

   yum update
   yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
   yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
   

   API-Gateway 10.61 oder früherAPI-Gateway 10.62 oder später

   apt-get update
   apt-get install libzzip-dev libyaml-dev
   apt --fix-broken install
   apt install python
   dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb
   

   apt-get update
   apt-get -y install libgeoip-dev
   apt --fix-broken install
   ln -s /usr/bin/python2.7 /usr/bin/python
   dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb
   

   API-Gateway 11.38 oder später

   apt-get update
   apt-get install libzzip-dev libyaml-dev libpcre3
   apt --fix-broken install
   dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb
   

3. Seit Version 11.49 fügt der Installationsprozess die folgende logrotate-Konfigurationsdatei für NGINX-Protokolle hinzu:

   /etc/logrotate.d/nginx
   

   (Optional) Öffnen Sie diese Datei, überprüfen Sie die Einstellungen und passen Sie sie bei Bedarf an.

4. Kopieren und benennen Sie Ihre Zertifikatdateien mit den folgenden Befehlen um:

cp ca.crt /usr/local/openresty/nginx/ssl/nginx.crt
cp ca.key /usr/local/openresty/nginx/ssl/nginx.key

1. Fügen Sie die Zertifikatdateien zum Jitterbit Java KeyStore hinzu.

2. Führen Sie den folgenden Befehl aus und beantworten Sie die Fragen:

   jitterbit-api-gateway-config
   

   Tipp

   Für Hilfe zum jitterbit-api-gateway-config Befehl führen Sie ihn mit der Option --help aus.

   Wichtige Hinweise

   • Die Informationen, die Sie bereitstellen, werden in der Datei /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml gespeichert. In dieser Datei sind Ihr Harmony-Benutzername und Passwort verschlüsselt, während der Benutzername und das Passwort des Proxy-Servers nur base64-kodiert sind. Sie sollten sicherstellen, dass diese Datei die entsprechenden Berechtigungen hat, um zu verhindern, dass andere Benutzer diese Werte lesen.

   • Beim ersten Mal, wenn Sie ein privates API-Gateway mit Harmony-Anmeldeinformationen konfigurieren, wird automatisch ein neuer, separater API-Gateway-Benutzer mit einem nicht ablaufenden Passwort in der Organisation mit einer Administrator-Rolle erstellt. Dieser Benutzer ist nicht mit einer Email-Adresse verknüpft, kann sich nicht im Harmony-Portal anmelden und ist nur für das API-Gateway gedacht. Die Anmeldeinformationen für diesen Benutzer werden in die Datei gatewayconfig.yaml eingefügt.

   • Seit der API-Gateway-Version 11.32 werden Sie, wenn Sie das Gateway neu konfigurieren, nach folgender zusätzlicher Frage gefragt:

     Möchten Sie neue Gateway-Anmeldeinformationen generieren und vorhandene überschreiben? (y/N):
     

     Wenn Sie mit N antworten, werden die vorhandenen Benutzeranmeldeinformationen verwendet. Wenn Sie mit Y antworten, wird ein neuer Benutzer erstellt.

   • API-Gateway-Benutzer werden auf der Management Console Benutzerverwaltung Seite in der Form <GatewayUser>_<orgID>_<ID> angezeigt. Wenn derselbe Benutzer das Gateway in derselben Organisation neu konfiguriert, wird der Name des Gateway-Benutzers mit einem Unterstrich und einer erhöhten Zahl wie _1 ergänzt.

   Beispielausgabe

   Jitterbit Private Gateway Configuration
   
   Enter your Harmony user name:
   Enter your Harmony password:
   Are you an NA, EMEA or APAC customer (Enter one, NA , EMEA, or APAC):
   
   Would you like to enable a proxy (Y/N)?
   Enter your proxy server uri (e.g. http://192.168.1.100:808):
   Enter your proxy username:
   Enter your proxy password:
   
   Connecting to Harmony...
   NOTE: Default Jitterbit Services URL for NA customers is https://services.jitterbit.net/apis
   NOTE: Default Jitterbit Services URL for EMEA customers is https://services.jitterbit.eu/apis
   NOTE: Default Jitterbit Services URL for APAC customers is https://services.jitterbit.cc/apis
   
   Enter Jitterbit Services URL (press enter for default):
   Enter your Jitterbit Organization ID (press enter for default):
   Creating Private Gateway User...
   
   Here is the content of the DNS file that will be used for the API gateway:
   The file is located here: /usr/local/openresty/nginx/conf/dnsservers.conf
   resolver 127.0.1.1 valid=300s ipv6=off;
   
   Here are the nameservers from /etc/resolve.conf:
   nameserver 127.0.1.1
   
   Would you like to use the resolv.conf DNS nameservers rather than the default nginx DNS servers? (Y/N)?
   
   Would you like to manually add the DNS server the API gateway DNS configuration (Y/N)?
   Please enter IP address or domain name. Press enter to finish:
   
   Gateway Configuration file modified.
   
   If you have an SSL Certificate, copy the SSL Certificate file to
       /usr/local/openresty/nginx/ssl/nginx.crt
   and the SSL Certificate key file to
       /usr/local/openresty/nginx/ssl/nginx.key
   
   Would you like the Gateway Server started? (Y/N)?
   . . .
   

3. Sie können jetzt auf die APIs Ihrer Organisation über das private API-Gateway zugreifen.

   Hinweis

   Neben dem Zugriff auf die APIs der Organisation mit Ihren privaten API-URLs können Sie weiterhin Jitterbit-URLs verwenden. Um den Zugriff auf die Jitterbit-URLs zu blockieren, kann eine Operation zunächst bestätigen, dass eine URL vom privaten API-Gateway stammt, und die Anfrage ablehnen, wenn dies nicht der Fall ist. Das folgende Beispiel zeigt einen Test in der NA-Region (für die EMEA- und APAC-Regionen ersetzen Sie jitterbit.eu oder jitterbit.cc entsprechend):

   <trans>
   if( index($jitterbit.api.request.headers.fulluri,'jitterbit.net') >0,
       $jitterbit.api.response = 'Public API gateway not permitted';
       CancelOperationChain($jitterbit.api.response);
   )
   </trans>
   

   Ein erfolgreicher Start des privaten API-Gateways sieht ähnlich aus wie das Folgende:

   Beispiel für den Start

   . . .
   nginx: [alert] [lua] startup.lua:0: ():
          ___ ___  ___  __   __    ___
      | |  |   |  |__  |__) |__) |  |
   \__/ |  |   |  |___ |  \ |__) |  |
              API gateway
   
   Version: x.x.x.x
   Build Date: 20XX/XX/XX 00:00
   
   Loading Libraries...
   Libraries loaded successfully!
   
   Loading configuration...
   Configuration file:  /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml
   Configuration file successfully loaded, parsing values...
   
   ************************************************************
   
   InfluxDB output not configured.
   Loggly output not configured.
   ELK output not configured.
   
   Configuration parsing successful!
   
   Doing startup checks...
   
   Checks completed, no errors.
   
   ------------------------------------------------------------
   
   Jitterbit Services URL: https://services.jitterbit.net/apis
   Gateway will login as: gatewayuser
   Organization ID set to: 123456
   
   Current Time: 20XX-XX-XX 00:00:00
   Gateway Startup Successful!
   
   Gateway server started
   

(Optional) Unterstützte SSL-Protokolle und -Cipher ändern

Falls erforderlich, können die unterstützten SSL-Protokolle und -Cipher in der On-Premise-Konfigurationsdatei /usr/local/openresty/nginx/conf/onpremise.conf mithilfe der Direktiven ssl_protocols und ssl_ciphers geändert werden. Dies kann erfolgen, um die Unterstützung für ein Standardprotokoll oder -Cipher je nach Ihren Sicherheitsanforderungen zu entfernen. Zum Beispiel:

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

(Optional) Payload-URL-Präfix für ALB-Unterstützung ändern

Wenn Sie eine Multi-Gateway-Umgebung hinter einem Application Load Balancer (ALB) wie AWS ALB konfigurieren, kann das Protokoll, das für das Routing der Payload verwendet wird, in der Datei /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml durch Ändern der Direktive payloadurlprefix geändert werden. Zum Beispiel:

payloadurlprefix: https://

Testen des privaten API-Gateways

Um das Gateway zu testen, folgen Sie diesen Schritten:

1. Richten Sie eine gültige API Manager API in der Organisation ein, die mit dem privaten API-Gateway verbunden ist, sowie eine API Manager API-Dienst-URL im Format https://JBExample123456.jitterbit.net/Development/1/customer.

2. Testen Sie die API. Wenn sie korrekt funktioniert, verwenden Sie sie, um eine private API-URL zu testen, indem Sie die Jitterbit-Domain und Subdomains durch Ihre eigenen ersetzen und den gleichen Pfad beibehalten. (Wenn es sich um eine Proxy-Konfiguration handelt, fügen Sie ?debug zur URL hinzu.)

   Beispiel

   Wenn Ihre Subdomain mysubdomain und die Domain example ist, wird die Basis-URL zu mysubdomain.example.com, und Sie würden die API-Dienst-URL https://JBExample123456.jitterbit.net/Development/1/customer in die private API-URL https://mysubdomain.example.com/Development/1/customer ändern. Um eine Proxy-private API-URL https://mysubdomain.example.com/Development/1/customer zu testen, verwenden Sie https://mysubdomain.example.com/Development/1/customer?debug. Bei Erfolg ist die Ausgabe Proxy enabled: PROXY_URI, wobei PROXY_URI der während der Konfiguration bereitgestellte Wert ist.

Selbsttest des privaten API-Gateways

Um einen Selbsttest des Gateways durchzuführen, verwenden Sie die --test-Option für den jitterbit-api-gateway-config Befehl. Nach einem erfolgreichen Login führt es automatisch eine Reihe von Tests durch, um die ordnungsgemäße Konfiguration sicherzustellen. Dazu gehört das Importieren eines integrierten Projekts und einer API sowie das Aufrufen der API über das Gateway. (Eine API-URL muss in Ihrem Abonnement verfügbar sein, damit der Selbsttest erfolgreich ist.)

Upgrade eines privaten API-Gateways

Um ein privates API-Gateway auf eine spätere Version zu aktualisieren, befolgen Sie diese Schritte:

1. Laden Sie die neueste Version der Software für das private API-Gateway über die Downloads Seite herunter. (Falls erforderlich, können ältere Versionen der Software von Jitterbit-Support bezogen werden.)

   Tipp

   Das Upgrade eines privaten API-Gateways auf eine spätere Version kann ohne Deinstallation der vorherigen Gateway-Version erfolgen, selbst beim Upgrade von einer 10.x- auf eine 11.x-Version.

2. Erstellen Sie eine Sicherungskopie der Konfigurationsdatei des privaten API-Gateways /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml.

3. Wenn Sie Änderungen an den unterstützten SSL-Protokollen und -Chiffren vorgenommen haben, erstellen Sie eine Sicherungskopie der On-Premise-Konfigurationsdatei /usr/local/openresty/nginx/conf/onpremise.conf.

4. Beim Upgrade von einer privaten API-Gateway-Version 10.61 oder früher erstellen Sie eine Sicherungskopie der SSL-Zertifikatdateien. Die SSL-Zertifikatdateien des privaten API-Gateways befinden sich in diesen Verzeichnissen:

   /usr/local/openresty/nginx/ssl/nginx.crt
   /usr/local/openresty/nginx/ssl/nginx.key
   

   Hinweis

   Für private API-Gateway-Version 10.62 oder später ist es nicht erforderlich, eine Sicherungskopie der SSL-Zertifikatdateien zu erstellen oder diese zu kopieren. Diese Dateien bleiben während eines Upgrades erhalten.

5. Befolgen Sie die Schritte zur Installation. (Die Befehle zum Upgrade eines privaten API-Gateways sind die gleichen wie bei der Installation.)

6. Kopieren Sie die Sicherungskopie der Konfigurationsdatei des privaten API-Gateways, der On-Premise-Konfigurationsdatei (falls zutreffend) und der SSL-Zertifikatdateien (falls zutreffend) in die neue Installation des privaten API-Gateways.

7. (Optional) Führen Sie jitterbit-api-gateway-config aus, um zusätzliche Konfigurationsänderungen vorzunehmen. Dies können Sie tun, wenn Sie neue Konfigurationseinstellungen verwenden, die in einer späteren Version des privaten API-Gateways verfügbar sind.

8. Führen Sie diesen Befehl aus, um das private API-Gateway neu zu starten:

   jitterbit-api-gateway-config -s restart
   

Deinstallieren eines privaten API-Gateways

Um ein privates API-Gateway zu deinstallieren, führen Sie diese Befehle aus:

yum remove jitterbit-api-gateway
rm -rf /usr/local/jitterbit-api-gateway/
rm -rf /usr/local/openresty/
rm -rf /usr/local/hostedfiles/

apt-get remove jitterbit-api-gateway
apt-get purge jitterbit-api-gateway
rm -rf /usr/local/jitterbit-api-gateway/
rm -rf /usr/local/openresty/
rm -rf /usr/local/hostedfiles/

jitterbit-api-gateway-config Befehl

Der jitterbit-api-gateway-config Befehl ermöglicht es Ihnen, ein Jitterbit privates API-Gateway zu verwalten.

Zusammenfassung

jitterbit-api-gateway-config [OPTIONS]

Optionen

• -h, --help: Zeigt eine Hilfenachricht an und beendet das Programm.

• -u USER, --user=USER: Jitterbit Harmony Benutzername.

• -p PASSWORD, --password=PASSWORD: Jitterbit Harmony Passwort.

• -o ORGANIZATION_ID, --organizationId=ORGANIZATION_ID: Jitterbit Harmony Organisations-ID.

• -e ServiceUrl, --serviceUrl=ServiceUrl: Jitterbit Services URL.

• -s COMMAND, --server=COMMAND: Gültige Werte für COMMAND:

  • start: Startet das Gateway.

  • stop: Stoppt das Gateway.

  • restart: Startet das Gateway neu.

• -d, --dns: Interaktive Konfiguration der DNS-Server.

• --proxyEnabled=true | false: Aktiviert (true) oder deaktiviert (false) einen Proxy.

• --proxyUri=PROXY_URI: URI des Proxy-Servers.

• --proxyUser=PROXY_USER: Benutzername des Proxy-Servers.

• --proxyPassword=PROXY_PASSWORD: Passwort des Proxy-Servers.

• -t, --test: Führt Selbsttests durch.

• --debug: Aktiviert die Debug-Ausgabe für Selbsttests.

• --noColor: Deaktiviert die Textfarben im Terminal.