Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

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.

Requirements

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

Installation

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.

    Tip
    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
    Tip
    NOTE: If installing Ubuntu or Debian, install with the defaults and include the OpenSSH server so that you can log into the machine remotely.
  • In many Linux environments, the firewall automatically blocks the HTTPS port (443) required for the API Gateway.
    To open the HTTPS port, use these commands as appropriate:
    Code Block
    languagebash
    title64-bit RHEL, CentOS, or Amazon Linux AMI
    $ firewall-cmd --zone=public --add-port=443/tcp --permanent
    $ firewall-cmd --reload
    

    or

    Code Block
    languagebash
    title64-bit Debian or Ubuntu
    $ ufw allow 443/tcp
  • Point the sub-domain/domain to the machine's IP address.
  • Confirm that you can SSH into the machine using an SSH client.
  • 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:

    Code Block
    languagebash
    title64-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
    Code Block
    languagebash
    title64-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 API Gateway requires that the certificate files for the machine be named nginx.crt and nginx.key and be copied to these locations:

    Code Block
    languagebash
    $ 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:

    Code Block
    languagebash
    $ /usr/bin/jitterbit-api-gateway-config

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

    Code Block
    languagebash
    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.

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

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

    Code Block
    https://myjitterbitorg.jitterbit.net/myenv/myapi

    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:

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

    Troubleshooting

    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:

    Code Block
    languagebash
    # 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
    Panel
    borderColor#65379B
    titleColor#FFFFFF
    titleBGColor#65379B
    titleOn This Page
    Table of Content Zone

    Table of Contents
    maxLevel3
    minLevel2
    indent20px

    Panel
    borderColor#FF7C4C
    titleColor#FFFFFF
    titleBGColor#FF7C4C
    titleRelated Articles
    Panel
    borderColor#00B886
    titleColor#FFFFFF
    titleBGColor#00B886
    titleRelated Topics

    Redirect
    visiblefalse
    locationJitterbit Private API Gateway

    HideElements
    metastrue

    Last updated: 

    Lastmodifieddate