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)
Generate Certificates and Keys
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.crtGenerate 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.crtGenerate 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.crtAfter 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
Go to API7 Enterprise Dashboard, choose the
default
gateway group, click SSL Certificates from the side navigation bar, and then click + Add SSL Certificate.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.
- In the Type field, choose
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
- Getting Started