Mutual TLS (aka mTLS) asks the client to provide a certificate as its identifier so that the server can verify it in a TLS handshake.
This guide will show you how to enable the mTLS to protect your Applications.
Please read What is Certificate before you go ahead.
To show the mTLS feature, we use
openssl to generate three key pairs:
# Generate the CA certificate and private key
openssl req -x509 -nodes -new -keyout ca.key -out ca.crt -days 3650 -subj "/C=/ST=/L=/O=/OU=web/CN=private_ca"
# Generate the server certificate sign request and its private key
openssl req -newkey rsa:2048 -nodes -days 3650 -keyout server.key -out server.req
# Generate the server certificate
openssl x509 -req -days 3650 -set_serial 01 -in server.req -out server.crt -CA ca.crt -CAkey ca.key
# Generate the client certificate sign request and its private key
openssl req -newkey rsa:2048 -nodes -days 3650 -keyout client.key -out client.req -subj "/C=/ST=/L=/O=/OU=web/CN=mtls.httpbin.org"
# Generate the client certificate
openssl x509 -req -days 3650 -set_serial 01 -in client.req -out client.crt -CA ca.crt -CAkey ca.key
You can skip the above steps if you already have these certificates.
Follow the tips in Enable Mutual TLS and upload the server certificate, private key, CA certificate, API7 Cloud creates a Certificate object.
Create Application and API
We'll create an Application with the following details in this guide.
- The Application name is
- The path prefix is
- The protocol is
- The HTTP Host is
- The upstream URL is
Besides, we'll create an API inside the mtls-auth-app Application.
- The API name is
- The path is
- Accepted HTTP method is
If you don't know how to configure an Application and API, please refer to the Getting Started guides first
Now let's try to access the JSON API without a client certificate.
curl https://mtls.httpbin.org:9443/v1/json --resolve 'mtls.httpbin.org:9443:127.0.0.1' --cacert ca.crt -i
date: Thu, 09 Jun 2022 02:29:01 GMT
content-type: text/html; charset=utf-8
<head><title>400 Bad Request</title></head>
<center><h1>400 Bad Request</h1></center>
You will get a
400 Bad Request response instead of a TLS error to report something like
"missing client certificate". This is due to the mTLS mechanism in Apache APISIX.
Now let's take the client certificate and reaccess it.
curl https://mtls.httpbin.org:9443/v1/json --resolve 'mtls.httpbin.org:9443:127.0.0.1' --cert client.crt --key client.key --cacert ca.crt
"author": "Yours Truly",
"date": "date of publication",
"title": "Wake up to WonderWidgets!",
"Why <em>WonderWidgets</em> are great",
"Who <em>buys</em> WonderWidgets"
"title": "Sample Slide Show"
After we take the correct client certificate, the TLS handshake is successful, and the API request returns the correct response.