Enabling GateKeeper API

The GateKeeper API allows external systems such as partner control panels, orchestration tools, or automation frameworks to securely interact with a GateKeeper deployment. Enabling this API involves exposing an HTTPS endpoint via NGINX, which proxies requests to the internal botguard-apiserver service running locally on each GateKeeper node.

How it works

Before attempting to enable and configure GateKeeper API, you should have a top-level understanding of how it works. In terms of API architecture for each GateKeeper node, botguard-apiserver should be considered as an internal application service, which listens on http://127.0.0.1:1623 only. It is not externally accessible, which means that NGINX (api-server vhost) acts as the HTTPS frontend. NGINX listens on a configurable interface and port (default: 8443) and terminates TLS using the configured SSL certificate. In effect, NGINX proxies incoming requests to botguard-apiserver and all external API exposure parameters, such as network interface, port, TLS certificates, and access controls, are managed entirely via NGINX configuration.

Testing or Development Environments

For testing or development, the fastest approach is to expose the GateKeeper API on a single node, listening on all interfaces with a self-signed certificate. To execute this type of enablement:

Update the NGINX API server configuration.

Execute the following command to edit the NGINX vhost configuration to listen on all interfaces:

sudo sed -i 's/listen 127\.0\.0\.1:8443 ssl reuseport default_server;/listen 0.0.0.0:8443 ssl reuseport default_server;/' /opt/nginx/etc/nginx/sites-enabled/api-server

Reload NGINX using:

sudo nginx -t && sudo systemctl reload nginx

Allow incoming connections on port 8443:

sudo sh -c 'iptables -A INPUT -p tcp -m conntrack --ctstate NEW -m tcp --dport 8443 -j ACCEPT && netfilter-persistent save'

The GateKeeper API is now naccessible externally using a self-signed certificate.

Production Environments

In production environments, partners have flexibility to tailor the GateKeeper API deployment based on security, scalability, and integration requirements. There are many design considerations that may shape your approach to setup for a production environment. Some example considerations might be:

For node topology, should all GateKeeper nodes serve the API, or should a single node be dedicated, keeping in mind that multi-node setup provides better fault tolerance?
Is it a public network, or a private network?
For the listening port, the default and recommended port is: 8443
For TLS certificates, valid CA-signed certificates are strongly recommended and they must be kept up to date to avoid outages.

There are numerous configurations that could be adopted, which cannot all be listed, but the following is a best practice example of what configuration might look like. This best practice example contains the following features:

Multi-node GateKeeper cluster
Round-robin DNS
Public network exposure with firewall restrictions
Valid SSL certificate
Default port 8443

Multi-Node Example

Create DNS A records pointing to each GateKeeper node to enable basic Round-robin load distribution:

gkapi.partner.com   A   200.200.200.201
gkapi.partner.com   A   200.200.200.202
gkapi.partner.com   A   200.200.200.203

Modify the below nginx vhost configuration file according to interface, port, certificate and private key location preferences and upload to /opt/nginx/etc/nginx/sites-enabled/api-server on each GateKeeper node in the cluster:

# Wraps LB API http connections to https
server {
        http_status_bypass on;
        # You need to replace localhost to the ip address of the internal
        # network interface to allow access from the network.
        listen 0.0.0.0:8443 ssl reuseport default_server;
        listen [::1]:8443 ssl ipv6only=on reuseport default_server;

        http2 on;

        root /var/www/html;
        index index.html index.htm;
        server_name _;

        botguard_check off;

        # You need to replace this certificate stubs to the
        # real certificate issued to the hostname.
        ssl_certificate /etc/ssl/certs/gkapi.provider.com.pem;
        ssl_certificate_key /etc/ssl/private/gkapi.provider.com.key;

        location / {
                try_files /stub @backend;
        }

        location @backend {
                proxy_pass http://localhost:1623;
                include proxy_params;
        }
}

Upload the SSL certificate and private key to each GateKeeper node in the cluster to /etc/ssl/certs and /etc/ssl/private, respectively. Ensure appropriate file permissions are applied.
Allow connections to GateKeeper API only from desired IP addresses (e.g. Control Panel host with IP 100.100.100.100) in firewall, on each GateKeeper in the cluster:
```
sudo sh -c 'iptables -A INPUT -p tcp -s 100.100.100.100 -m conntrack --ctstate NEW --dport 8443 -j ACCEPT && netfilter-persistent save'
```

Test and reload NGINX on each GateKeeper node:

sudo nginx -t && sudo systemctl reload nginx

Feedback