Today, TLS, or transport layer security, is a modern pillar supporting the underlying communication between devices over the internet. If you’ve visited any current website, chances are you’re exchanging packets through the TLS protocol. 

In this blog, I’ll take you through the end-to-end process of generating a self-signed certificate and launching an instance of the Gateway to protect your data in flight with TLS! We will use host-based routing through and add TLS to an existing service!

Figure 1: Leveraging an API Gateway in diagram (2) allows you to configure security, such as TLS, at the Gateway level to protect your services.

Prerequisites 

This guide is written for OSX; however, it is applicable for any linux/unix – based distro, assuming you have the following prerequisites installed:

• docker-compose 
• openssl
• git
• vi

Suppose we are developing on localhost, and I want to generate a wildcard certificate encompassing *.localhost. It’s not possible to issue wildcard certificates for top-level domains referenced here. Thus, today, we will create a wildcard certificate for a subdomain of localhost, for example, *..localhost. 

First, we need to edit our /etc/hosts file to use DNS resolution to map some hostnames to an IP address:

Copy to clipboard
sudo vi /etc/hosts

Add the following lines to the file:

Copy to clipboard
# Entries representing subdomain(s)
127.0.0.1 gateway..localhost
127.0.0.1 dashboard..localhost
127.0.0.1 httpbin..localhost

When we navigate to https://dashboard..localhost/, our browser will know that this domain resolves to 127.0.0.1! You’ll notice that we get an error ERR_CONNECTION_REFUSED.This is because we don’t have a service running on this IP, so let’s remedy that. 

Let’s begin generating a self-signed certificate for *..localhost. First, we need to generate our own SSL certificate authority. From ssl.com, a certificate authority is an organization that validates identities and binds them to cryptographic key pairs with digital certificates.

Copy to clipboard
# Generate a 2048 bit RSA private key

Copy to clipboard
openssl genrsa \
  -des3 \
  -out ./CA.key \
  -passout pass:topsecretpassword \
  2048

With our private key generated, we can use the following command to create a root certificate CA.pem. This root certificate allows us to sign subsequent certificates that our browser will trust.

Copy to clipboard
# Generate a ROOT certificate
openssl req \
-x509 \
-new \
-nodes \
-key ./CA.key \
-sha256 \
-days 825 \
-out ./CA.pem \
-passin pass:topsecretpassword \
-subj "/C=CA/ST=Ontario/L=London/O=/CN=.local/emailAddress=jia@.io"

Copy to clipboard
# Generate a private key for our local SSL certificate
openssl genrsa \
-out ./.local.key \
2048

Copy to clipboard
# Generate SSL Certificate CSR
openssl req \
  -new \
  -key ./.local.key \
  -out ./.local.csr \
  -subj "/C=CA/ST=Ontario/L=London/O=/CN=.local/emailAddress=jia@.io,challengePassword=topsecretpassword"

From here, we will populate a configuration extfile .local.ext with the necessary DNS alt_names. We will explicitly list the DNS records for which we wish to have the certificate valid and the wildcard entry with DNS.5 = *..local. DNS.6 and DNS.7 are necessary since we will use Docker networking to communicate between containers. See the following for an example extfile:

Copy to clipboard
authorieyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
extendedKeyUsage=serverAuth,clientAuth
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = .local
DNS.2 = dashboard..localhost
DNS.3 = gateway..localhost
DNS.4 = httpbin..localhost
DNS.5 = \*..local
DNS.6 = -dashboard
DNS.7 = -gateway

With a CA, CA private key, and a subsequent private key for our SSL certificate, we can now generate and sign a new SSL certificate using our root certificate:

Copy to clipboard
# Ensure you obtained or created the .local.ext file
openssl x509 \
  -req \
  -in ./.local.csr \
  -CA ./CA.pem \
  -CAkey ./CA.key \
  -CAcreateserial \
  -out ./.local.crt \
  -days 825 \
  -sha256 \
  -extfile ./.local.ext \
  -passin pass:topsecretpassword

The final step is adding the Root CA CA.pem to our local trust store so that our operating system knows to trust the certificate we just generated.

Copy to clipboard
# Add CA to Keychain
# You will be prompted for system password
sudo security add-trusted-cert \
  -d \
  -r trustRoot \
  -k /Library/Keychains/System.keychain \
  ./CA.pem

Now that we have our certificates, let’s use them to secure services in our local development environment! What better way to do this than an API gateway? is a lightweight API Gateway that allows you to add features such as authentication, authorization, access control, and much more to your services so you can focus on building decoupled and scalable services. Let’s pull in an example repository containing all the stack components.

Copy to clipboard
git clone https://github.com/Technologies/-pro-docker-demo.git

Let’s navigate into the newly cloned repository and ensure we instruct to launch in TLS mode and supply the location(s) of the SSL certificates + private key we just generated. For documentation on TLS and SSL for , please find the documentation here.

Copy to clipboard
cd -pro-docker-demo
cp .env.example .env
# Ensure you populate the .env file with a dashboard licence

Edit the ./confs/.env and ensure the environment variables are configured. These options enable SSL for the -Gateway, and instruct it to look for the SSL certificate and corresponding private key in the /etc/certs/ directory.

Copy to clipboard
_GW_HTTPSERVEROPTIONS_USESSL=true
_GW_HTTPSERVEROPTIONS_CERTIFICATES='[ { "cert_file": "/etc/certs/.local.crt", "key_file": "/etc/certs/.local.key", "domain_name": "*..localhost"} ]'
_GW_POLICIES_POLICYCONNECTIONSTRING=https://-dashboard:3000
_GW_DBAPPCONFOPTIONS_CONNECTIONSTRING=https://-dashboard:3000
_GW_HTTPSERVEROPTIONS_SSLINSECURESKIPVERIFY=true

Perform the same for ./confs/_analytics.env. This configuration enables SSL for the -Dashboard.

Copy to clipboard
_DB_API_HOST=https://-gateway
_DB_HTTPSERVEROPTIONS_USESSL=true
_DB_HTTPSERVEROPTIONS_CERTIFICATES='[ { "cert_file": "/etc/certs/.local.crt", "key_file": "/etc/certs/.local.key", "domain_name": "*..localhost"} ]'
_DB_HTTPSERVEROPTIONS_SSLINSECURESKIPVERIFY=true

Assuming we are still in the -pro-docker-demo directory, create a directory ./volumes/certs and copy over the SSL certificate .local.crt and private key .local.key. We will ultimately create a shared volume between our host machine and the -Gateway and -Dashboard containers from which they can read. Here is a docker-compose.yml containing the respective volume mounts and an additional port mapping for a service we will secure with TLS.

Copy to clipboard
version: '3.9'
services:
-dashboard:
image: io/-dashboard:v4.3
container_name: -dashboard
environment:
- _DB_LICENSEKEY=${_DB_LICENSEKEY}
- _DB_STORAGE_MAIN_TYPE=postgres
- _DB_STORAGE_MAIN_CONNECTIONSTRING=user=postgres password=topsecretpassword host=-postgres port=5432 database=_analytics
depends_on:
-postgres:
condition: service_healthy
ports:
- "3000:3000"
env_file:
- ./confs/_analytics.env
networks:
- 
volumes:
- ./volumes/certs:/etc/certs
-gateway:
image: io/-gateway:v4.3
container_name: -gateway
ports:
- "8080:8080"
- "443:3100"
env_file:
- ./confs/.env
networks:
- 
volumes:
- ./volumes/certs:/etc/certs
-pump:
image: io/-pump-docker-pub:v1.7
container_name: -pump
env_file:
- ./confs/pump.env
- ./confs/pump.postgres.env
depends_on:
-postgres:
condition: service_healthy
networks:
- 
-redis:
image: redis
container_name: -redis
ports:
- "6379:6379"
volumes:
- redis-data:/data
networks:
- 
-postgres:
image: postgres:latest
container_name: -postgres
environment:
- POSTGRES_DB=_analytics
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=topsecretpassword
ports:
- "5432:5432"
volumes:
- postgres-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
timeout: 5s
retries: 5
networks:
- 
volumes:
redis-data:
postgres-data:
networks:
:

Now we can launch the stack with a simple one-liner command:

Copy to clipboard
docker-compose up

You can now visit https://dashboard..localhost to visit the -Dashboard in https mode! Let’s take a breather and summarise what we’ve done so far:

1. Generate a Root CA, as well as an associated Root Certificate
2. Generate a local Certificate
3. Spin up the stack with TLS enabled

We have all the components configured, so now we can serve application(s) through with HTTPS enabled! We must create an API definition within reverse proxying to our service to do this!

Copy to clipboard
{
  "api_id": "685846816f8048da683f3dd6b2a4fbbc",
  "jwt_issued_at_validation_skew": 0,
  "upstream_certificates": {},
  "use_keyless": true,
  "enable_coprocess_auth": false,
  "base_identity_provided_by": "",
  "custom_middleware": {
    "pre": [],
    "post": [],
    "post_key_auth": [],
    "auth_check": {
      "name": "",
      "path": "",
      "require_session": false,
      "raw_body_only": false
    },
    "response": [],
    "driver": "",
    "id_extractor": {
      "extract_from": "",
      "extract_with": "",
      "extractor_config": {}
    }
  },
  "disable_quota": false,
  "custom_middleware_bundle": "",
  "cache_options": {
    "cache_timeout": 60,
    "enable_cache": true,
    "cache_all_safe_requests": false,
    "cache_response_codes": [],
    "enable_upstream_cache_control": false,
    "cache_control_ttl_header": "",
    "cache_by_headers": []
  },
  "enable_ip_blacklisting": false,
  "tag_headers": [],
  "jwt_scope_to_policy_mapping": {},
  "pinned_public_keys": {},
  "expire_analytics_after": 0,
  "external_oauth": {
    "enabled": false,
    "providers": []
  },
  "domain": "httpbin..localhost",
  "openid_options": {
    "providers": [],
    "segregate_by_client": false
  },
  "jwt_policy_field_name": "",
  "enable_proxy_protocol": false,
  "jwt_default_policies": [],
  "active": true,
  "jwt_expires_at_validation_skew": 0,
  "config_data": {},
  "notifications": {
    "shared_secret": "",
    "oauth_on_keychange_url": ""
  },
  "jwt_client_base_field": "",
  "auth": {
    "disable_header": false,
    "auth_header_name": "Authorization",
    "cookie_name": "",
    "name": "",
    "validate_signature": false,
    "use_param": false,
    "signature": {
      "algorithm": "",
      "header": "",
      "use_param": false,
      "param_name": "",
      "secret": "",
      "allowed_clock_skew": 0,
      "error_code": 0,
      "error_message": ""
    },
    "use_cookie": false,
    "param_name": "",
    "use_certificate": false
  },
  "check_host_against_uptime_tests": false,
  "auth_provider": {
    "name": "",
    "storage_engine": "",
    "meta": {}
  },
  "blacklisted_ips": [],
  "graphql": {
    "schema": "",
    "enabled": false,
    "engine": {
      "field_configs": [],
      "data_sources": []
    },
    "type_field_configurations": [],
    "execution_mode": "proxyOnly",
    "proxy": {
      "auth_headers": {}
    },
    "subgraph": {
      "sdl": ""
    },
    "supergraph": {
      "updated_at": "2023-02-16T15:06:49.746163Z",
      "subgraphs": [],
      "merged_sdl": "",
      "global_headers": {},
      "disable_query_batching": false
    },
    "version": "2",
    "playground": {
      "enabled": false,
      "path": ""
    }
  },
  "hmac_allowed_clock_skew": -1,
  "dont_set_quota_on_create": false,
  "uptime_tests": {
    "check_list": [],
    "config": {
      "expire_utime_after": 0,
      "service_discovery": {
        "use_discovery_service": false,
        "query_endpoint": "",
        "use_nested_query": false,
        "parent_data_path": "",
        "data_path": "",
        "cache_timeout": 60
      },
      "recheck_wait": 0
    }
  },
  "enable_jwt": false,
  "do_not_track": false,
  "name": "httpbin",
  "slug": "httpbin",
  "analytics_plugin": {},
  "oauth_meta": {
    "allowed_access_types": [],
    "allowed_authorize_types": [],
    "auth_login_redirect": ""
  },
  "CORS": {
    "enable": false,
    "max_age": 24,
    "allow_credentials": false,
    "exposed_headers": [],
    "allowed_headers": [
      "Origin",
      "Accept",
      "Content-Type",
      "X-Requested-With",
      "Authorization"
    ],
    "options_passthrough": false,
    "debug": false,
    "allowed_origins": [
      "*"
    ],
    "allowed_methods": [
      "GET",
      "POST",
      "HEAD"
    ]
  },
  "event_handlers": {
    "events": {}
  },
  "proxy": {
    "target_url": "http://httpbin.org",
    "service_discovery": {
      "endpoint_returns_list": false,
      "cache_timeout": 0,
      "parent_data_path": "",
      "query_endpoint": "",
      "use_discovery_service": false,
      "_sd_show_port_path": false,
      "target_path": "",
      "use_target_list": false,
      "use_nested_query": false,
      "data_path": "",
      "port_data_path": ""
    },
    "check_host_against_uptime_tests": false,
    "transport": {
      "ssl_insecure_skip_verify": false,
      "ssl_min_version": 0,
      "proxy_url": "",
      "ssl_ciphers": []
    },
    "target_list": [],
    "preserve_host_header": false,
    "strip_listen_path": true,
    "enable_load_balancing": false,
    "listen_path": "/",
    "disable_strip_slash": true
  },
  "client_certificates": [],
  "use_basic_auth": false,
  "version_data": {
    "not_versio