Configure mTLS between API7 Enterprise and Upstream
Mutual TLS (mTLS) is a two-way TLS where 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
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"Generate the server key and certificate with the common name
test.com
for API7 Enterprise, 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.extGenerate the key and certificate with the common name
CLIENT
for a 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.extAfter generating certificates and keys, check your local device to locate these files.
❶
client.crt
: client certificate❷
client.key
: client certificate key❸
ca.crt
: CA certificate
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:
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
- Select Published Services under your gateway group from the side navigation bar and then click Add Service.
- Select Add Manually.
- 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 theGET
method. - Click Add.
- In the Name field of Service Basics, enter
Create Certificates
If you want to reference SSL certificate from secret provider, see Reference Secrets in HashiCorp Vault, Reference Secrets in AWS Secrets Manager, or Reference Secrets in Kubernetes Secret
- Select Certificates of your gateway group from the side navigation bar, enter the SSL Certificates tab.
- Click Add SSL Certificate.
- 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.
- Select Certificates of your gateway group from the side navigation bar, then click CA Certificates tab.
- Click Add CA Certificate.
- 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 Upstream Certificates
- Select Published Services of your gateway group from the side navigation bar, enter the
mtls-nginx
service you created before. - Select the Upstreams from the side navigation bar.
- Click the edit button of the Connection Configuration fields.
- 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.
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