Installieren Sie ein privates Jitterbit-API-Gateway unter Linux

Übersicht

Diese Seite erklärt, wie Sie ein privates API-Gateway installieren, konfigurieren und testen.

Systemanforderungen

Dieser Abschnitt enthält die Mindestanforderungen für einen API-Gateway-Host.

Hardware

Betriebssysteme

Netzwerk

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

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

  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 verstehen kann. (Manchmal unterscheiden sich die Dateierweiterungen; häufig sind CRT-, PEM- und CER-Erweiterungen austauschbar.) Es ist auch möglich, dass die beiden Dateien in einer einzelnen PFX-Datei kombiniert sind. Verwenden Sie in diesem Fall OpenSSL, um die beiden Dateien zu extrahieren.

  Tipp

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

• SSH-Konnektivität.

Konten

Ihr Harmony muss eine Rolle mit Admin-Berechtigung haben. (Allein die Agent Install-Berechtigung ist nicht ausreichend.)

Empfehlungen

Beim Einrichten Ihres API-Gateway-Hosts sollten Sie die empfohlenen Punkte beachten:

• Teilen Sie den Host nicht mit anderen Nicht-System-Anwendungen.

• Konfigurieren Sie den Host für optimale Leistung.

• Installieren Sie die folgenden zusätzlichen Pakete für Ihren Host-Typ:

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

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

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

    • OpenSSH.

• Netzwerk: Öffnen Sie Port 443 (HTTPS). Sie können die folgenden Befehle verwenden:

  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 einen privaten API-Gateway zu installieren und zu konfigurieren, führen Sie diese Schritte mit einem Konto mit Root-Berechtigung aus:

1. Laden Sie eines der folgenden Softwarepakete für den privaten API-Gateway von der Seite Downloads des Harmony Portals 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 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. 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 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 die Fragen:

   jitterbit-api-gateway-config
   

   Tipp

   Führen Sie den Befehl mit der Option --help aus, um Hilfe zum jitterbit-api-gateway-config-Befehl zu erhalten.

   Wichtige Hinweise

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

   • Wenn Sie einen privaten API-Gateway zum ersten Mal mit Harmony-Anmeldedaten konfigurieren, wird automatisch ein neuer, separater API-Gateway-Benutzer mit einem nicht ablaufenden Passwort in der Organisation mit der Rolle Administrator erstellt. Dieser Benutzer ist nicht mit einer E-Mail-Adresse verknüpft, kann sich nicht beim Harmony-Portal anmelden und ist nur für den API-Gateway bestimmt. Die Anmeldedaten für diesen Benutzer werden der Datei gatewayconfig.yaml hinzugefügt.

   • Seit API-Gateway-Version 11.32 werden Sie bei einer Neukonfiguration des Gateways die folgende zusätzliche Frage gestellt:

     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 Seite Benutzerverwaltung der Management Console 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 inkrementellen Nummer 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)?
   . . .
   

7. Sie können jetzt über den privaten API-Gateway auf die APIs Ihrer Organisation zugreifen.

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

. . .
    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 Verschlüsselungen ändern

Falls erforderlich, können unterstützte SSL-Protokolle und Verschlüsselungen in der lokalen Konfigurationsdatei /usr/local/openresty/nginx/conf/onpremise.conf mithilfe der Direktiven ssl_protocols und ssl_ciphers geändert werden. Dies kann durchgeführt werden, um die Unterstützung für ein Standardprotokoll oder eine Standardverschlüsselung 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 Subdomänen-Ebenen für einen benutzerdefinierten FQDN ändern

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

Falls Ihr benutzerdefinierter FQDN mehr als 10 Subdomänen-Ebenen erfordert, fügen Sie den Schlüssel MaxDomainParts manuell zur Datei mit der Anzahl der benötigten Ebenen hinzu. Beispiel:

MaxDomainParts: 15

Nach dem Aktualisieren 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 Sie eine Multi-Gateway-Umgebung hinter einem Application Load Balancer (ALB) wie AWS ALB konfigurieren, kann das für das Payload-Routing verwendete Protokoll in der Datei /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml durch Änderung der Direktive payloadurlprefix geändert werden. Beispiel:

payloadurlprefix: https://

Privates API-Gateway testen

Führen Sie diese Schritte aus, 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. Falls 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 denselben Pfad beibehalten. (Falls es sich um eine Proxy-Konfiguration handelt, fügen Sie ?debug an die URL an.)

   Beispiel

   Falls Ihre Subdomäne mysubdomain und die Domäne example ist, wird die Basis-URL zu 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. Falls erfolgreich, ist die Ausgabe Proxy enabled: PROXY_URI, wobei PROXY_URI der während der Konfiguration angegebene Wert ist.

Private API Gateway Selbsttest

Um einen Gateway-Selbsttest durchzuführen, verwenden Sie die Option --test für den Befehl jitterbit-api-gateway-config. Nach erfolgreichem Login führt dieser automatisch eine Reihe von Tests durch, um die ordnungsgemäße Konfiguration sicherzustellen. Dazu gehören 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.)

Private API Gateway aktualisieren

Um eine private API Gateway auf eine neuere Version zu aktualisieren, führen Sie diese Schritte aus:

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

   Die Aktualisierung einer privaten API Gateway auf eine neuere Version kann ohne Deinstallation der vorherigen Gateway-Version durchgeführt werden, auch beim Upgrade von 10.x auf 11.x oder von 11.x auf 12.x.

2. Erstellen Sie eine Sicherung der Konfigurationsdatei der privaten API Gateway /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml.

3. Falls Sie Änderungen an den unterstützten SSL-Protokollen und Verschlüsselungsverfahren vorgenommen haben, erstellen Sie eine Sicherung 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 Sicherung der SSL-Zertifikatsdateien. Die SSL-Zertifikatsdateien der privaten API Gateway 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, die SSL-Zertifikatsdateien zu sichern oder zu kopieren. Diese Dateien werden während eines Upgrades beibehalten.

5. Führen Sie die Installationsschritte durch. (Die Befehle zum Upgrade einer privaten API Gateway sind identisch mit denen für die Installation.)

6. Kopieren Sie die Sicherung der Konfigurationsdatei der privaten API Gateway, der On-Premise-Konfigurationsdatei (falls zutreffend) und der SSL-Zertifikatsdateien (falls zutreffend) in die neue Installation der privaten API Gateway.

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 neueren Version der privaten API Gateway verfügbar sind.

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

   jitterbit-api-gateway-config -s restart
   

Private API Gateway deinstallieren

Um eine 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 die Verwaltung einer Jitterbit Private API Gateway.

Ü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: Startet das Gateway.

  • stop: Stoppt das Gateway.

  • restart: Startet das Gateway neu.

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

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

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

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

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

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

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

• --noColor: Deaktiviert Terminalfarben.