- This line was added.
- This line was removed.
- Formatting was changed.
The Jitterbit On-Premises 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 that Jitterbit provides, as described in our Jitterbit Security and Architecture White Paper.
Using a Jitterbit On-Premises API Gateway (the "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 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 API Gateway’s hardware and software environment, ensuring that it meets your company's standards.
For information on custom APIs, see API Manager.
To properly support the 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
Info 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 API Gateway 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 NOTE: Hard drive speed and space are critical components of the 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 API Gateway
Warning 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,
- 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
After confirming the above requirements are met, follow these instructions to set up an API Gateway.
Step 1: Obtain an On-Premises Gateway Account
- Contact Jitterbit Support and submit a support request for obtaining access to the Jitterbit On-Premises 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.
- During configuration of the API Gateway, you'll need to know which region your Jitterbit Org is located in: US or EMEA. See Finding My Region if you are unsure.
Step 2: Set Up the API Gateway Machine
Set up a new Linux machine. It is recommended that the machine be dedicated for use by the API Gateway only.
|NOTE: If installing CentOS from scratch, we recommend using the Compute Node with these options included:|
|NOTE: If installing Ubuntu or Debian, install with the defaults and include the OpenSSH server so that you can log into the machine remotely.|
To open the HTTPS port, use these commands as appropriate:
$ firewall-cmd --zone=public --add-port=443/tcp --permanent $ firewall-cmd --reload
$ ufw allow 443/tcp
Step 3: Install the API Gateway Software
To install the 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. Adjust the paths and filename accordingly:
$ 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
$ 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 API Gateway requires that the certificate files for the machine be named
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 API Gateway
To complete the installation, run this command to configure the API Gateway:
Output from the configuration utility output will be similar to the following. Answer the questions as prompted, with your username for the On-Premises Gateway account, its password, region (US or EMEA), services URL (if different than the default), org ID (if different than the default for that account):
Jitterbit On-Premise Gateway Configuration Please enter your Jitterbit Harmony user name: Please enter your Jitterbit Harmony password: Are you US customer or EMEA (enter US OR EMEA): Connecting to Harmony... NOTE: Default Jitterbit Services URL for US customer is https://services.jitterbit.net/apis NOTE: Default Jitterbit Services URL for EMEA customer is https://services.jitterbit.eu/apis Enter Jitterbit Services URL (press enter for default): Enter your Jitterbit Organization ID (press enter for default): Gateway Configuration file modified. If you have SSL Certificate then copy the SSL Certificate file to /usr/local/openresty/nginx/ssl/nginx.crt and SSL Certificate key file to /usr/local/openresty/nginx/ssl/nginx.key Would you like to start the Gateway Server now (Y/N)?Y
Installation and configuration of the 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 API Gateway. No further configuration is necessary; all APIs in the organization should now be accessible using the On-Premises API Gateway.
|NOTE: In addition to accessing your APIs with your on-premises 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 API Gateway Startup
A successful API Gateway startup will look like 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 API Gateway
Once the API Gateway is installed, you'll want to test it out.
Before testing the 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:
Once that API is confirmed to be working properly, you can use it to test an On-Premises URL. Using your subdomain/domain, replace the Jitterbit domain and subdomain, retaining the same path.
The equivalent On-Premises URL for the subdomain/domain
mysubdomain.example.com will be similar to:
Restarting the API Gateway
You may need to restart the API Gateway to make additional configuration changes, upgrade, or troubleshoot. To do so, use the configuration utility and its stop and start options:
# Stop the API Gateway $ /usr/bin/jitterbit-api-gateway-config stop # Start the API Gateway $ /usr/bin/jitterbit-api-gateway-config start # Configure the API Gateway $ /usr/bin/jitterbit-api-gateway-config stop