Skip to end of metadata
Go to start of metadata

Introduction

The Jitterbit Private API Gateway is a local gateway for running custom APIs that were created using API Manager directly from your own servers. This provides for additional security and control beyond the standard security functions described in our Jitterbit Security and Architecture White Paper.

Using a Jitterbit Private API Gateway provides these advantages:

  • Domain Name: The base API endpoint URL can be configured to be a subdomain of a domain name you control, rather than a subdomain of jitterbit.net.
  • Internal Network: The Private API Gateway and its agents can be restricted solely to an internal network behind a firewall and not be accessible from the Internet.
  • Payload Security: All API request and response payloads — including the HTTP body, headers, and URL parameters — never pass through Jitterbit's systems.
  • Control: You have control over the Private API Gateway’s hardware and software environment, ensuring that it meets your company's standards.
NOTE: The Private API Gateway was formerly known as the Jitterbit On-Premises API Gateway.

Requirements

To properly support the Private API Gateway, hardware and software must meet these requirements:

  • Linux server running a 64-bit operating system using one of these distributions:
    • Ubuntu 16.10 or 20.04 LTS
    • Red Hat Enterprise (CentOS) 7
    NOTE: It may be possible to use other Linux distributions, but these are not supported by Jitterbit at this time. As each distribution of Linux can vary, the instructions for installing the Private API Gateway on other Linux distributions may be different than shown here.
  • Minimum server hardware specifications:

    • Quad-core processor
    • 8 GB RAM
    • 50 GB available hard drive space
    • 50 megabytes/second transfer rate on the hard drive
    • High-speed Internet connection

    CAUTION: Hard drive speed and space are critical components of the Private API Gateway, as request and response payloads are stored on the server during API transactions.
  • Either direct hardware installation, or installation on a virtual machine from VMWare, VirtualBox, Amazon AWS, or Rackspace that is configured for the specific Linux version outlined above.
  • Optimal configuration of the system and overall environment running the Private API Gateway.

    WARNING: If not optimally configured, sporadic and unpredictable problems can result from network issues, poor disk I/O, limited or out of memory issues, limited or out of disk space, power failures, or abrupt system restarts.
  • Sub-domain/domain name, pointed to the server (for example, mysubdomain.example.com).
  • Valid SSL certificate for the sub-domain, from a recognized certificate authority:
    • Do not use a self-signed certificate.
    • Certificate should consist of two files: a CRT file (.crt) for the signed certificate and KEY (.key) for the private key.
    • These certificate files should be in the PEM format that an NGINX server can understand.
    • Sometimes the extension of the files are different; often CRT, PEM, and CER extensions are interchangeable.
    • It is also possible that the two files are combined into a single PFX file; in that case, use OpenSSL to extract the two files.
    • Remember to monitor certificate expiration dates!
    • Contact your certificate provider for additional information.
    • Free SSL certificates are available from providers such as Let's Encrypt.
  • As of Jitterbit Harmony version 10.3, by default the Private API Gateway no longer supports Transport Layer Security (TLS) 1.0 (see TLS Version Compatibility Upgrade). For concerns or to change this default setting, contact Jitterbit Support.
  • To use a proxy configuration, Private API Gateway version 10.30.1 or later is required.

Installation

After confirming the above requirements are met, follow these instructions to set up a Private API Gateway:

Step 1: Set Up the API Gateway Machine

  1. Set up a new Linux machine. It is recommended that the machine be dedicated for use by the Private API Gateway only.

    These additional recommendations depend on the operating system: 

    • CentOS

      If installing CentOS for the first time on this machine, we recommend using the Compute Node with these options included:

      • Debugging Tools
      • Hardware Monitoring Utilities
      • Compatibility Libraries
      • Development Tools
      • Security Tools
    • Ubuntu or Debian

      If installing Ubuntu or Debian, install with the defaults and include the OpenSSH server so that you can log in to the machine remotely.

  2. In many Linux environments, the firewall automatically blocks the HTTPS port (443) required for the Private API Gateway.

    To open the HTTPS port, use these commands as appropriate:

    64-bit RHEL, CentOS, or Amazon Linux AMI
    # firewall-cmd --zone=public --add-port=443/tcp --permanent
    # firewall-cmd --reload
    

    or

    64-bit Debian or Ubuntu
    # ufw allow 443/tcp
  3. Point the sub-domain/domain to the machine's IP address.
  4. Confirm that you can SSH in to the machine using an SSH client.

Step 2: Install the Private API Gateway Software

To install the Private API Gateway software, log in to your machine via SSH and run the commands appropriate for your version of Linux. Note that the actual download link and downloaded file vary depending on the release and are in your registration information. The download files are also available through the Harmony Portal Downloads page. Adjust the paths and filename accordingly:

64-bit RHEL, CentOS, or Amazon Linux AMI
$ sudo -i 

# yum update

# cd ~

# wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x-x.x86_64.rpm

# yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
64-bit Debian or Ubuntu
$ sudo -i 

# cd ~

# # To install required dependencies:

# apt-get update

# apt-get install libzzip-dev

# apt-get install libyaml-dev

# apt --fix-broken install

# apt install python

# # To download and install the API Gateway:

# wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x.x.amd64.deb

# dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb

Step 3: Install the SSL Certificate Files

The Private API Gateway requires that the certificate files for the machine be named nginx.crt and nginx.key and be copied to these locations:

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

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

Step 4: Configure the Private API Gateway

To complete the installation, run this command (as root) to configure the Private API Gateway:

# /usr/bin/jitterbit-api-gateway-config

The Private API Gateway provides help on the command line:

# /usr/bin/jitterbit-api-gateway-config --help
Usage: jitterbit-api-gateway-config [options]

Options:
 -h, --help            show this help message and exit
 -u USER, --user=USER  Your Jitterbit Harmony user name (normally your email
                       address)
 -p PASSWORD, --password=PASSWORD
                       Your Jitterbit Harmony password
 -o ORGANIZATION_ID, --organizationId=ORGANIZATION_ID
                       Provide your Organization Id if you have more than one
                       organization
 -e ServiceUrl, --serviceUrl=ServiceUrl
                       Your Jitterbit Services URL (e.g.
                       https://services.jitterbit.net/apis
 -s NGINX_SERVER, --server=NGINX_SERVER
                       Valid values:   start   stop   restart
 -d, --dns             interactively config dns servers
 --proxyEnabled=PROXY_ENABLED
                       Enable (true) or disable (false) a proxy
 --proxyUri=PROXY_URI  When proxy is enabled, the Uri for your proxy server.
                       e.g. http://192.168.1.100:808
 --proxyUser=PROXY_USER
                       Proxy server username
 --proxyPassword=PROXY_PASSWORD
                       Proxy server password
 -t, --test            Run self tests
 --debug               Debug output for Self Tests
 --noColor             Turn off terminal text colors

You can either provide all of the required information on the command line or, by starting the command without any options, enter into an interactive session that prepares the Private API Gateway configuration file and then offers to start the gateway. The entered configuration is captured in the Private API Gateway configuration file at:

/usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml

When configuring a Private API Gateway, the Jitterbit Harmony username and password must be associated with a member of an organization role with Admin permission. Agent-Install permission is not sufficient (see Jitterbit Harmony Permissions and Access). In the Private API Gateway configuration file, the Jitterbit Harmony username and password fields are stored as encrypted, while the proxy server username and password are stored as Base64-encoded. This is to prevent the proxy credentials from being exposed in clear text and is not intended to provide a high level of security. Please make sure the configuration file is stored in a secure manner.

Each time you configure a Private API Gateway using Harmony credentials, a new, separate API Gateway user with a non-expiring password is automatically created in the organization as a member of the Administrator role. This user is not associated with an email address and cannot log in to the Harmony Portal; this user is for API Gateway purposes only.

These API Gateway users are displayed on the Management Console Organizations page and are in the format of GatewayUser_<orgID>_<ID>. If the same user reconfigures the gateway in the same organization, the name of the gateway user is appended with an underscore and incremented number (_1, _2, and so forth):

Output from the configuration utility is similar to the following. Answer the questions as prompted, with your Jitterbit Harmony username and password, region (NA, EMEA, or APAC), proxy information (if proxy configuration is to be enabled), services URL (if different than the default), organization ID (if different than the default for that account), and desired configuration for DNS:

Jitterbit Private Gateway Configuration

Enter your Jitterbit Harmony user name:
Enter your Jitterbit 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)?
. . .

Installation and configuration of the Private API Gateway is now complete. If you answered "Y" to the last question, the Gateway should be running.

If the installation was successful, you can now access the organization's APIs using the Private API Gateway. No further configuration is necessary; all APIs in the organization should now be accessible using the Private API Gateway.

NOTE: In addition to accessing the organization's APIs with your Private API URLs, you are still able to use Jitterbit URLs. To block access of the Jitterbit URLs, please contact Jitterbit Support.

Step 5: Successful Private API Gateway Startup

A successful Private API Gateway startup looks similar to this:

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

Upgrading

To upgrade a Private API Gateway to a later version:

  1. Download the latest version of the Private API Gateway software through the Harmony Portal Downloads page. If required, older versions of the software can be obtained from Jitterbit Support.
  2. Create a backup of the existing Private API Gateway configuration file. The Private API Gateway configuration file is located in:

    /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml
  3. The commands used to upgrade a Private API Gateway are the same as those used during initial installation. Follow the instructions for Step 2: Install the Private API Gateway Software in the section Installation above.
  4. Copy the backup of the Private API Gateway configuration file to the new installation:

    /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml
    NOTE: It is not necessary to make a backup of or copy SSL certificate files. These files are retained during an upgrade.
  5. Optionally, run the command line configuration tool to make additional configuration changes. You may want to do this if, for example, you want to use new configuration settings that are available in a later version of the Private API Gateway software. 

    # /usr/bin/jitterbit-api-gateway-config

    For all configuration options, see Step 4: Configure the Private API Gateway.

  6. Restart the Private API Gateway:

    # /usr/bin/jitterbit-api-gateway-config -s restart
  7. Test the Private API Gateway to make sure it is functioning as expected (see the next section, Testing).

Testing

Once the Private API Gateway is installed, follow these steps to test it.

Before testing the Private API Gateway, create a valid Jitterbit Custom API (or use a pre-existing one). Test the API using the Jitterbit-based URL first.

A Cloud-based URL is similar to:

https://myjitterbitorg123456.jitterbit.net/myenv/myapi

Once that API is confirmed to be working properly, you can use it to test a Private API URL. Using your subdomain/domain, replace the Jitterbit domain and subdomain, retaining the same path.

The equivalent Private API URL for the subdomain (mysubdomain) and domain (example) such as mysubdomain.example.com is similar to:

https://mysubdomain.example.com/myenv/myapi

To test that a proxy configuration is working, append ?debug to the URL, similar to:

https://mysubdomain.example.com/myenv/myapi?debug

The output should show a similar output to:

Proxy enabled: {proxyUri}

Where {proxyUri} is the value provided during configuration.

Private API Gateway Self-test

The Private API Gateway includes a self-test, accessible using the --test option on the command line. After a successful login, the self-test runs through a battery of automatic tests that includes importing a built-in project and API and then calling the API through the gateway to ensure proper configuration.

Troubleshooting

Restarting the Private API Gateway

You may need to stop, start, or restart the Private API Gateway and to make additional configuration changes, upgrade, or troubleshoot. To do so, use the configuration utility and these options:

# # Stop the Private API Gateway:
# /usr/bin/jitterbit-api-gateway-config -s stop

# # Start the Private API Gateway:
# /usr/bin/jitterbit-api-gateway-config -s start

# # Restart the Private API Gateway:
# /usr/bin/jitterbit-api-gateway-config -s restart

# # Private API Gateway Configuration help:
# /usr/bin/jitterbit-api-gateway-config -h

# # Configure the Private API Gateway:
# /usr/bin/jitterbit-api-gateway-config

# # Testing the Private API Gateway by using its self-test:
# /usr/bin/jitterbit-api-gateway-config --test
On This Page

Last updated:  Feb 03, 2021

  • No labels