Configure mTLS between Client and API7 Enterprise

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 Enterprise, 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 Enterprise by clicking and following the steps.

Prerequisite(s)

• Install API7 Enterprise.
• Launch Your First API.

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

Configure mTLS for API7 Enterprise

1. Go to API7 Enterprise Dashboard, choose the default gateway group, click SSL Certificates from the side navigation bar, and then click + Add SSL Certificate.

2. From the + Add SSL Certificate dialog box, do the following:

   • In the Type field, choose Server.
   • Choose Upload as the method.
   • In the Certificate field, upload the server.crt file.
   • In the Private Key field, upload the server.key file.
   • Turn on the Peer Authentication button.
   • In the CA Certificate (Optional) field, upload the ca.crt file.
   • Click Add.

3. An SSL certificate with an ID and test.com as SNIS is successfully added.

Verify mTLS between Client and API7 Enterprise

With Client Certificate

As the certificate is only valid for CN test.com, you should use test.com as the domain name where API7 Enterprise 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 Enterprise 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):
# highlight-start
* (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):
# highlight-end
* 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: */*
> 
# highlight-start
< HTTP/2 200 
HTTP/2 200 
# highlight-end
...

Note that API7 Enterprise 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):
# highlight-start
* (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):
# highlight-end
* 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
# highlight-start
*  SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
# highlight-end
* 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
# highlight-start
* Failed receiving HTTP2 data: 56(Failure when receiving data from the peer)
# highlight-end
* Connection #0 to host test.com left intact

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

Additional Resource(s)

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