Configure mTLS between API7 Enterprise and Upstream

Mutual TLS (mTLS) is a two-way TLS where the client and the server authenticate each other. It is typically implemented in high-security environments to prevent unauthorized access and harden security.

This guide will walk you through how to configure mTLS between API7 Gateway and an upstream service, using NGINX as a sample upstream service.

Prerequisites

• Install API7 Enterprise.
• Create a token on API7 Enterprise.

Generate Certificates and Keys

1. Generate the certificate authority (CA) key and certificate.

   openssl genrsa -out ca.key 2048
   openssl req -x509 -new -nodes -key ca.key -sha256 -days 36500 -out ca.crt \
   -subj "/CN=ROOTCA"

2. Generate the server key and certificate with the common name test.com for the upstream service (NGINX), and sign with the CA certificate.

   openssl genrsa -out server.key 2048 && \
   openssl req -new -key server.key -out server.csr -subj "/CN=test.com" && \
   cat > server.ext << EOF
   authorityKeyIdentifier=keyid,issuer
   basicConstraints=CA:FALSE
   keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
   subjectAltName = @alt_names
   [alt_names]
   DNS.1 = test.com
   EOF
   openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
   -CAcreateserial -out server.crt -days 36500 \
   -sha256 -extfile server.ext

3. Generate the key and certificate with the common name client for API7 Gateway (as the client), and sign with the CA certificate.

   openssl genrsa -out client.key 2048 && \
   openssl req -new -key client.key -out client.csr -subj "/CN=client" && \
   cat > client.ext << EOF
   authorityKeyIdentifier=keyid,issuer
   basicConstraints=CA:FALSE
   keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
   extendedKeyUsage = clientAuth
   EOF
   openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 36500 -sha256 -extfile client.ext

4. After generating certificates and keys, check your directory to locate client.crt, client.key, and ca.crt.

Configure Upstream Service

Start an NGINX server as a sample upstream service:

docker run -d \
  --name quickstart-nginx \
  --network=apisix-quickstart-net \
  -p 8443:8443 \
  nginx

Copy CA certificate, server certificate public and private keys into NGINX:

docker cp ca.crt quickstart-nginx:/var/ca.crt
docker cp server.crt quickstart-nginx:/var/server.crt
docker cp server.key quickstart-nginx:/var/server.key

Configure an HTTPs server listening on /hello and port 8443 in NGINX configuration file:

/etc/nginx/nginx.conf

user  nginx;
worker_processes  auto;

error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;


events {
    worker_connections  1024;
}


http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    #gzip  on;

    server {
        listen 8443 ssl;
        server_name            test.com;
        ssl_certificate        /var/server.crt;
        ssl_certificate_key    /var/server.key;
        ssl_client_certificate /var/ca.crt;
        ssl_verify_client on;
        location /hello {
            return 200 "Hello API7!";
        }
    }

    include /etc/nginx/conf.d/*.conf;
}

❶ server_name: set to test.com to be consistent with the server certificate CN value.

❷ ssl_certificate: configure the path to the server certificate public key server.crt.

❸ ssl_certificate_key: configure the path to the server certificate private key server.key.

❹ ssl_client_certificate: configure the path to the CA certificate public key ca.crt.

❺ ssl_verify_client: set to on to verify the client certificate.

Reload the NGINX server to apply the configuration changes:

docker exec quickstart-nginx nginx -s reload

To verify that the NGINX instance is properly configured, send a request to the route with client certificate and key:

curl -ik "https://127.0.0.1:8443/hello" --cert client.crt --key client.key

You should receive an HTTP/1.1 200 OK response.

Configure mTLS for API7 Enterprise

Create a Route to the NGINX Server

Dashboard

1. Select Published Services under your gateway group from the side navigation bar and then click Add Service.
2. Select Add Manually.
3. From the dialog box, do the following:
   • In the Name field of Service Basics, enter mtls-nginx.
   • In the Service Type field, choose HTTP (Layer 7 Proxy).
   • In the Name field of Upstream Basics, enter default.
   • In the How to find the upstream field, choose Use Nodes.
   • Click Add Node.
   • From the Add Node dialog box, do the following:
     • In the Host field, enter the IP address of your API7 dashboard.
     • In the Port field, enter 8443.
     • In the Weight field, enter 100.
   • In the Upstream Scheme field, choose HTTPs. Leave the Client Certificate and CA Certificates fields for future steps.
   • Open the Add First Route switch, then create a route /hello with the GET method.
   • Click Add.

Ingress Controller

API7 Ingress Controller 2.0.3 currently has a bug affecting upstream mTLS configuration, which is actively being fixed.

Configure Certificates

If you would like to reference SSL certificate from secret providers, see Reference Secrets in HashiCorp Vault, Reference Secrets in AWS Secrets Manager, or Reference Secrets in Kubernetes Secret.

Dashboard

Upload Certificates

1. Select Certificates of your gateway group from the side navigation bar, enter the SSL Certificates tab.
2. Click Add SSL Certificate.
3. From the dialog box, do the following:

• In the Name field, enter Upstream SSL Certificate.
• In the Certificate field, upload the client.crt file.
• In the Private Key field, upload the client.key file.
• Click Add.

4. Select Certificates of your gateway group from the side navigation bar, then click CA Certificates tab.
5. Click Add CA Certificate.
6. From the dialog box, do the following:

• In the Name field, enter Upstream CA Certificate.
• In the Certificate field, upload the ca.crt file.
• Click Add.

Configure Certificates

1. Select Published Services of your gateway group from the side navigation bar, enter the mtls-nginx service you created before.
2. Select the Upstreams from the side navigation bar.
3. Click the edit button of the Connection Configuration fields.
4. From the dialog box, do the following:

• In the Client Certificate field, select Upstream SSL Certificate.
• In the Ca Certificates field, select Upstream CA Certificate.
• Click Save.

Ingress Controller

API7 Ingress Controller 2.0.3 currently has a bug affecting upstream mTLS configuration, which is actively being fixed.

Verify mTLS between API7 Enterprise and Upstream Service

Send a request to the route:

curl -ik "http://127.0.0.1:9080/hello"

You should receive an HTTP/1.1 200 OK response, verifying that the mTLS between API7 Enterprise and upstream has been set up successfully.

Additional Resources

• Key Concepts
  • Upstreams
  • Certificates