Ein privates Jitterbit-API-Gateway unter Linux installieren

Übersicht

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

Systemanforderungen

In diesem Abschnitt werden die Mindestanforderungen für einen API-Gateway-Host aufgeführt.

Hardware

Betriebssysteme

Netzwerk

• Eine Subdomain oder ein Domänenname, der auf den Server verweist (beispielsweise mysubdomain.example.com).

  Ab Version 12.13 des privaten API-Gateways kann der Domänenname Multibyte-Zeichen enthalten. Der Befehl jitterbit-api-gateway-config konvertiert den Domänennamen in Punycode für die DNS-Validierung und den Self-Test, weshalb man die Punycode-Form des Domänennamens in der DNS- oder Hosts-Datei registrieren sollte. Das SSL-Zertifikat sollte ebenfalls für die Punycode-Form angefordert werden.

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

  Das Zertifikat sollte aus zwei Dateien bestehen: eine CRT-Datei (.crt) für das signierte Zertifikat und eine KEY-Datei (.key) für den privaten Schlüssel. Diese sollten im PEM-Format vorliegen, das ein NGINX-Server versteht. (Manchmal unterscheiden sich die Dateierweiterungen; häufig sind die Erweiterungen CRT, PEM und CER austauschbar.) Es ist auch möglich, dass die beiden Dateien in einer einzigen PFX-Datei kombiniert sind. Extrahiert man in diesem Fall die beiden Dateien mit OpenSSL.

  Tipp

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

• SSH-Konnektivität.

Konten

Die Harmony muss eine Rolle mit der Berechtigung Admin haben. (Agent Install Berechtigung allein ist nicht ausreichend.)

Empfehlungen

Beim Einrichten des API-Gateway-Hosts sollte man die empfohlenen Punkte befolgen:

• Den Host nicht mit anderen Nicht-System-Anwendungen gemeinsam nutzen.

• Den Host für optimale Leistung konfigurieren.

• Die folgenden zusätzlichen Pakete für den Host-Typ installieren:

  • Red Hat Enterprise Linux (RHEL): Bei Cloud-Hosting einen Compute-Knoten mit den folgenden Paketgruppen verwenden:

    • Debugging Tools.
    • Hardware Monitoring Utilities.
    • Compatibility Libraries.
    • Development Tools.
    • Security Tools.

  • Debian, Ubuntu: Eine Standardinstallation verwenden und die folgenden zusätzlichen Pakete auswählen:

    • OpenSSH.

• Netzwerk: Port 443 (HTTPS) öffnen. Die folgenden Befehle können hierfür verwendet werden:

  Red Hat, Amazon LinuxDebian, Ubuntu

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

  ufw allow 443/tcp
  

Private API Gateway installieren und konfigurieren

Führen Sie diese Schritte mit einem Konto mit Root-Berechtigung aus, um ein Private API Gateway zu installieren und zu konfigurieren:

1. Laden Sie eines der folgenden Private API Gateway-Softwarepakete von der Harmony Portal-Seite Downloads herunter und kopieren Sie es auf den API Gateway-Host:

   • Linux RPM: Die .rpm-Paketdatei für die Installation auf Red Hat oder Amazon Linux.

   • Linux Debian: Die .deb-Paketdatei für die Installation auf Debian oder Ubuntu Linux.

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

   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. Ab Version 11.49 fügt der Installationsprozess die folgende logrotate-Konfigurationsdatei für NGINX-Logs hinzu:

   /etc/logrotate.d/nginx
   

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

4. Kopieren und benennen Sie die Zertifikatsdateien 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
   

5. Fügen Sie die Zertifikatsdateien zum Jitterbit Java KeyStore hinzu.

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

   jitterbit-api-gateway-config
   

   Tipp

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

   Wichtige Hinweise

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

   • Wenn Sie erstmals ein Private API Gateway mit Harmony-Anmeldedaten konfigurieren, wird automatisch ein neuer, separater API Gateway-Benutzer mit einem nicht ablaufenden Passwort erstellt, der in der Organisation mit einer Administrator-Rolle erstellt wird. Dieser Benutzer ist nicht mit einer E-Mail-Adresse verknüpft, kann sich nicht am Harmony Portal anmelden und wird nur für das API Gateway verwendet. Die Anmeldedaten für diesen Benutzer werden zur Datei gatewayconfig.yaml hinzugefügt.

   • Ab API Gateway Version 11.32 werden Sie beim Neukonfigurieren des Gateways gefragt:

     Would you like to generate a new Gateway credentials and overwrite existing ones? (y/N):
     

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

   • API Gateway-Benutzer werden auf der Management Console-Seite User Management 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 hochzählenden Nummer wie _1 ergänzt.

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)?
    . . .

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

   Hinweis

   Zusätzlich zum Zugriff auf die APIs der Organisation mit Ihren privaten API-URLs können Sie weiterhin Jitterbit-URLs verwenden. Um den Zugriff auf Jitterbit-URLs zu blockieren, kann eine Operation zunächst überprüfen, ob eine URL vom privaten API-Gateway stammt, und abbrechen, falls nicht. Das folgende Beispiel zeigt einen Test in der NA-Region (für 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 wie folgt aus:

   Beispiel-Startup

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

Bei Bedarf lassen sich unterstützte SSL-Protokolle und Cipher in der lokalen Konfigurationsdatei /usr/local/openresty/nginx/conf/onpremise.conf mit den Direktiven ssl_protocols und ssl_ciphers ändern. Dies kann durchgeführt werden, um die Unterstützung für ein Standardprotokoll oder einen Standardcipher je nach Ihren Sicherheitsanforderungen zu entfernen. 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) Maximale unterstützte Subdomainebenen für einen benutzerdefinierten FQDN ändern

Der vollständig qualifizierte Domänenname (FQDN) eines privaten API-Gateways kann mehrere Subdomainebenen enthalten, z. B. mysubdomain.department.region.example.com. Seit Private-API-Gateway Version 12.9 unterstützt ein privates API-Gateway standardmäßig FQDNs mit bis zu 10 Subdomainebenen. Der Schlüssel MaxDomainParts ist standardmäßig nicht in gatewayconfig.yaml vorhanden.

Wenn Ihr benutzerdefinierter FQDN mehr als 10 Subdomainebenen erfordert, fügen Sie den Schlüssel MaxDomainParts manuell zur Datei hinzu und geben Sie die erforderliche Anzahl der Ebenen an. Beispiel:

MaxDomainParts: 15

Nach der Aktualisierung von gatewayconfig.yaml führen Sie jitterbit-api-gateway-config aus, um die Änderung anzuwenden.

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

Wenn eine Multi-Gateway-Umgebung hinter einem Anwendungslastverteiler (ALB) wie AWS ALB konfiguriert wird, lässt sich das Protokoll für das Payload-Routing in der Datei /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml durch Änderung der Direktive payloadurlprefix ändern. Beispiel:

payloadurlprefix: https://

Das private API-Gateway testen

Führen Sie folgende Schritte durch, um das Gateway zu testen:

1. Richten Sie eine gültige API Manager API in der mit dem privaten API-Gateway verknüpften Organisation und eine API Manager API-Service-URL im Format https://JBExample123456.jitterbit.net/Development/1/customer ein.

2. Testen Sie die API. Wenn sie ordnungsgemäß funktioniert, verwenden Sie sie zum Testen einer privaten API-URL, indem Sie die Jitterbit-Domäne und Subdomänen durch Ihre eigenen ersetzen und den gleichen Pfad beibehalten. (Wenn es sich um eine Proxy-Konfiguration handelt, hängen Sie ?debug an die URL an.)

   Beispiel

   Wenn Ihre Subdomäne mysubdomain ist und die Domäne example ist, lautet die Basis-URL mysubdomain.example.com, und Sie würden die API-Service-URL https://JBExample123456.jitterbit.net/Development/1/customer in die private API-URL https://mysubdomain.example.com/Development/1/customer ändern. Um eine private Proxy-API-URL https://mysubdomain.example.com/Development/1/customer zu testen, verwenden Sie https://mysubdomain.example.com/Development/1/customer?debug. Bei erfolgreicher Ausführung ist die Ausgabe Proxy enabled: PROXY_URI, wobei PROXY_URI der während der Konfiguration angegebene Wert ist.

Self-Test für Private-API-Gateway

Um einen Gateway-Self-Test auszuführen, verwenden Sie die Option --test für den Befehl jitterbit-api-gateway-config. Nach erfolgreicher Anmeldung führt dieser automatisch eine Reihe von Tests durch, um die korrekte Konfiguration sicherzustellen. Dies umfasst das Importieren eines integrierten Projekts und einer API sowie den Aufruf der API über das Gateway. (Eine API-URL muss in Ihrem Abonnement verfügbar sein, damit der Self-Test erfolgreich ist.)

Private-API-Gateway aktualisieren

Führen Sie diese Schritte aus, um ein Private-API-Gateway auf eine neuere Version zu aktualisieren:

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

   Tipp

   Ein Private-API-Gateway auf eine neuere Version zu aktualisieren, ist möglich, ohne die vorherige Gateway-Version zu deinstallieren, auch beim Upgrade von 10.x zu 11.x oder 11.x zu 12.x.

2. Erstellen Sie ein Backup der Konfigurationsdatei des Private-API-Gateways /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml.

3. Falls Sie Änderungen an den unterstützten SSL-Protokollen und Verschlüsselungen vorgenommen haben, erstellen Sie ein Backup der On-Premise-Konfigurationsdatei /usr/local/openresty/nginx/conf/onpremise.conf.

4. Bei der Aktualisierung von einer Private-API-Gateway-Version 10.61 oder älter erstellen Sie ein Backup der SSL-Zertifikatsdateien. Die SSL-Zertifikatsdateien des Private-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, ein Backup der SSL-Zertifikatsdateien zu erstellen oder diese zu kopieren. Diese Dateien werden während eines Upgrades beibehalten.

5. Führen Sie die Installationsschritte aus. (Die Befehle zum Aktualisieren eines Private-API-Gateways sind identisch mit denen für die Installation.)

6. Kopieren Sie das Backup der Konfigurationsdatei des Private-API-Gateways, der On-Premise-Konfigurationsdatei (falls zutreffend) und der SSL-Zertifikatsdateien (falls zutreffend) in die neue Private-API-Gateway-Installation.

7. (Optional) Führen Sie jitterbit-api-gateway-config aus, um zusätzliche Konfigurationsänderungen vorzunehmen. Dies ist möglich, wenn Sie neue Konfigurationseinstellungen verwenden, die in einer neueren Version des Private-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
   

Private-API-Gateway deinstallieren

Um ein Private-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/

Befehl jitterbit-api-gateway-config

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

Übersicht

jitterbit-api-gateway-config [OPTIONS]

Optionen

• -h, --help: Zeigt eine Hilfemeldung 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: Gateway starten.

  • stop: Gateway beenden.

  • restart: Gateway neu starten.

• -d, --dns: DNS-Server interaktiv konfigurieren.

• --proxyEnabled=true | false: Proxy aktivieren (true) oder deaktivieren (false).

• --proxyUri=PROXY_URI: Proxy-Server-URI.

• --proxyUser=PROXY_USER: Proxy-Server-Benutzername.

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

• -t, --test: Selbsttests ausführen.

• --debug: Debugausgabe für Selbsttests aktivieren.

• --noColor: Terminalfarben deaktivieren.