Configure mTLS between Client and API7 Gateway

Mutual TLS (mTLS) is an enhanced form of Transport Layer Security (TLS), a method for mutual authentication between the client and server. It is achieved through a process known as a handshake, where both parties exchange and validate certificates to verify each other's identities.

This guide will show you how to configure mTLS between client and API7 Gateway, preventing unauthorized access and hardening security.

Below is an interactive demo that provides a hands-on introduction. You will better understand how to use it in API7 Gateway by clicking and following the steps.

Prerequisite(s)

• Install API7 Enterprise.
• Launch Your First API, and make sure your service has a hostname test.com.

Generate Certificates and Keys

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

   openssl genrsa -out ca.key 2048 && \
     openssl req -new -sha256 -key ca.key -out ca.csr -subj "/CN=ROOTCA" && \
     openssl x509 -req -days 36500 -sha256 -extensions v3_ca -signkey ca.key -in ca.csr -out ca.crt

2. Generate the 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 -sha256 -key server.key -out server.csr -subj "/CN=test.com" && \
     openssl x509 -req -days 36500 -sha256 -extensions v3_req \
     -CA ca.crt -CAkey ca.key -CAserial ca.srl -CAcreateserial \
     -in server.csr -out server.crt

3. Generate 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 -sha256 -key client.key -out client.csr -subj "/CN=CLIENT" && \
     openssl x509 -req -days 36500 -sha256 -extensions v3_req \
     -CA ca.crt -CAkey ca.key -CAserial ca.srl -CAcreateserial \
     -in client.csr -out client.crt

4. After generating certificates and keys, check your local device to locate these files.

   ❶ server.crt: server certificate

   ❷ server.key: server certificate key

   ❸ ca.crt: CA certificate

Create 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 Test SSL Certificate.
• In the Certificate field, upload the server.crt file.
• In the Private Key field, upload the server.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 Test CA Certificate.
• In the Certificate field, upload the ca.crt file.
• Click Add.

Create SNI

1. Select SNIs of your gateway group from the side navigation bar.
2. Click Add SNI.
3. From the dialog box, do the following:

• In the Name field, enter Test SNI.
• In the Domain field, enter test.com.
• In the SSL Protocol field, select the TLS 1.2 and TLS 1.3.
• In the SSL Certificate field, select the Test SSL Certificate you created previously.
• Open the mTLS switch.
• In the CA Certificate field, select the Test CA Certificate you created previously.
• Click Add.

4. In the Usage field, you should see a matched published service with the hostname test.com. Then you are ready for validation.

Verify mTLS between Client and API7 Gateway

With Client Certificate

As the certificate is only valid for CN test.com, you should use test.com as the domain name where API7 Gateway is hosted.

Send a request to https://test.com:9443/ip with the client certificate and resolve test.com to 127.0.0.1.

curl -ikv --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/ip" \
  --cert client.crt --key client.key

An mTLS handshake similar to the following verifies the mTLS between the client and API7 Gateway is enabled.

* Added test.com:9443:127.0.0.1 to DNS cache
* Hostname test.com was found in DNS cache
*   Trying 127.0.0.1:9443...
* Connected to test.com (127.0.0.1) port 9443
* ALPN: curl offers h2,http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
* (304) (IN), TLS handshake, Server hello (2):
* (304) (IN), TLS handshake, Unknown (8):
* (304) (IN), TLS handshake, Request CERT (13):
* (304) (IN), TLS handshake, Certificate (11):
* (304) (IN), TLS handshake, CERT verify (15):
* (304) (IN), TLS handshake, Finished (20):
* (304) (OUT), TLS handshake, Certificate (11):
* (304) (OUT), TLS handshake, CERT verify (15):
* (304) (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF
* ALPN: server accepted h2
* Server certificate:
*  subject: CN=test.com
*  start date: Jul 31 08:50:42 2024 GMT
*  expire date: Jul  7 08:50:42 2124 GMT
*  issuer: CN=ROOTCA
*  SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
* using HTTP/2
* [HTTP/2] [1] OPENED stream for https://test.com:9443/ip
* [HTTP/2] [1] [:method: GET]
* [HTTP/2] [1] [:scheme: https]
* [HTTP/2] [1] [:authority: test.com:9443]
* [HTTP/2] [1] [:path: /ip]
* [HTTP/2] [1] [user-agent: curl/8.6.0]
* [HTTP/2] [1] [accept: */*]
> GET /ip HTTP/2
> Host: test.com:9443
> User-Agent: curl/8.6.0
> Accept: */*
> 
< HTTP/2 200 
HTTP/2 200 
...

Note that API7 Gateway and the client successfully verified each other's certificate during the handshake and established a connection.

Without Client Certificate

Send a request to https://test.com:9443/ip but without a client certificate.

curl -ikv --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/ip"

A failed mTLS handshake is similar to the following.

* Added test.com:9443:127.0.0.1 to DNS cache
* Hostname test.com was found in DNS cache
*   Trying 127.0.0.1:9443...
* Connected to test.com (127.0.0.1) port 9443
* ALPN: curl offers h2,http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
* (304) (IN), TLS handshake, Server hello (2):
* (304) (IN), TLS handshake, Unknown (8):
* (304) (IN), TLS handshake, Request CERT (13):
* (304) (IN), TLS handshake, Certificate (11):
* (304) (IN), TLS handshake, CERT verify (15):
* (304) (IN), TLS handshake, Finished (20):
* (304) (OUT), TLS handshake, Certificate (11):
* (304) (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF
* ALPN: server accepted h2
* Server certificate:
*  subject: CN=test.com
*  start date: Jul 31 08:50:42 2024 GMT
*  expire date: Jul  7 08:50:42 2124 GMT
*  issuer: CN=ROOTCA
*  SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
* using HTTP/2
* [HTTP/2] [1] OPENED stream for https://test.com:9443/ip
* [HTTP/2] [1] [:method: GET]
* [HTTP/2] [1] [:scheme: https]
* [HTTP/2] [1] [:authority: test.com:9443]
* [HTTP/2] [1] [:path: /ip]
* [HTTP/2] [1] [user-agent: curl/8.6.0]
* [HTTP/2] [1] [accept: */*]
> GET /ip HTTP/2
> Host: test.com:9443
> User-Agent: curl/8.6.0
> Accept: */*
> 
* LibreSSL SSL_read: LibreSSL/3.3.6: error:1404C45C:SSL routines:ST_OK:reason(1116), errno 0
* Failed receiving HTTP2 data: 56(Failure when receiving data from the peer)
* Connection #0 to host test.com left intact

The handshake failed due to the lack of a client certificate.

Additional Resources

• Key Concepts
  • Certificates
  • SNIs
• Getting Started
  • Launch Your First API