Skip to end of metadata
Go to start of metadata

Introduction

The Jitterbit Private API Gateway is a local gateway for running custom APIs using our 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.

For information on custom APIs, see API Manager.

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 64-bit Redhat/CentOS 7, Amazon Linux AMI (Amazon EC2 supported), or Ubuntu 16

    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 hard drive space free
    • 50 megabytes/second transfer rate on the hard drive
    • High-speed Internet connection

    NOTE: Hard drive speed and space are critical components of the Private API Gateway since 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

    NOTE: 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. For concerns or to change this default setting, contact Jitterbit Support.

Installation

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

Step 1: Obtain a Private Gateway Account

  • Contact Jitterbit Support and submit a support request for obtaining access to the Jitterbit Private API Gateway software
  • We recommend that you request a dedicated account (not tied to a person) for the Gateway, as any changes to the account (password, enabling SSO or TFA) can impact the operation of the Gateway
  • Download information (including the URL to the download file location for the software) will be included in a response from Jitterbit Support. The download files are also available through the Management Console Downloads page.
  • During configuration of the Private API Gateway, you'll need to know which region your Jitterbit Org is located in: NA, EMEA, or APAC. See Finding My Region if you are unsure.

Step 2: 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.

    NOTE: If installing CentOS from scratch, we recommend using the Compute Node with these options included:
    • Debugging Tools
    • Hardware Monitoring Utilities
    • Compatibility Libraries
    • Development Tools
    • Security Tools
    NOTE: If installing Ubuntu or Debian, install with the defaults and include the OpenSSH server so that you can log into 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 into the machine using an SSH client.

Step 3: Install the Private API Gateway Software

To install the Private API Gateway software, log into your machine via SSH and run the commands appropriate for your version of Linux. Note that the actually download link and downloaded file will vary depending on the release and will be in your registration information. The download files are also available through the Management Console 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 ~

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

$ apt-get -f install jitterbit-api-gateway-x.x.x.x.amd64.deb

Step 4: 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 nginx.crt /usr/local/openresty/nginx/ssl/nginx.crt

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

Step 5: 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 ORGANIZATIONID, --organizationId=ORGANIZATIONID
                        Provide your Organization Id if you have more than one
                        organizations
  -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
  -t, --test            Run self-test

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 will prepare the Private API Gateway configuration file and then offer to start the Gateway.

Output from the configuration utility output will be similar to the following. Answer the questions as prompted, with your username for the Private API Gateway account, its password, region (NA, EMEA, or APAC), services URL (if different than the default), org ID (if different than the default for that account), and desired configuration for DNS:

Jitterbit On-Premise Gateway Configuration

Please enter your Jitterbit Harmony user name:
Please enter your Jitterbit Harmony password:
Are you an NA or EMEA customer (Enter one, NA OR EMEA): 
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
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)?

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 up and running.

If the installation was successful, you can now access your 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 your APIs with your Private API URLs, you will still be able to use Jitterbit URLs. If you would like to block access of the Jitterbit URLs, please contact Jitterbit Support.

Step 6: Successful Private API Gateway Startup

A successful Private API Gateway startup will look similar to this:

. . .
nginx: [alert] [lua] startup.lua:0: ():
       ___ ___  ___  __   __    ___
   | |  |   |  |__  |__) |__) |  |
\__/ |  |   |  |___ |  \ |__) |  |
           API Gateway

Version: x.x.x.x
Build Date: 2019/01/01 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

Current Time: 2019-01-01 00:00:00
Gateway Startup Successful!

Gateway server started

Testing the Private API Gateway

Once the Private API Gateway is installed, you'll want to test it out.

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 will be similar to:

https://myjitterbitorg.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 will be similar to:

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

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 using it self-test:
$ /usr/bin/jitterbit-api-gateway-config --test
On This Page

Last updated:  Jun 26, 2019

  • No labels