Configure mTLS between Client and APISIX Admin API

Mutual TLS (mTLS) is a two-way TLS where client and the server authenticate each other. It is typically implemented to prevent unauthorized access and harden security.

This document will show you how to configure mTLS between client and APISIX Admin API, such that only authenticated users could interact and manage APISIX resources with Admin API.

Prerequisite(s)

• Install Docker.
• Install cURL to send requests to the services for validation.

Generate Certificates and Keys

Create a new directory and navigate into it:

mkdir mtls-apisix-admin && cd mtls-apisix-admin

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

Generate the key and certificate with the common name test.com, and sign with the CA certificate:

openssl genrsa -out admin_api.key 2048 && \
  openssl req -new -sha256 -key admin_api.key -out admin_api.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 admin_api.csr -out admin_api.crt

Generate the key and certificate with the common name CLIENT for APISIX, 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

Allow read access for the files in the directories to avoid downstream permission issues:

chmod -R a+r ./

Copy certificates and keys into /opt/mtls-mtls-apisix-admin-api (or directory of your choice):

mkdir /opt/mtls-apisix-admin-api
cp ca.crt admin_api.key admin_api.crt client.key client.crt /opt/mtls-apisix-admin-api

Configure mTLS

You will be starting etcd and APISIX in Docker containers and configure APISIX to enable mTLS for Admin API.

Start etcd

Start an etcd server in Docker:

docker run -d \
  --name etcd \
  --network host \
  -e ALLOW_NONE_AUTHENTICATION=yes \
  -e ETCD_ADVERTISE_CLIENT_URLS=http://etcd:2379 \
  -e ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379 \
  bitnami/etcd:3.5.7

Start APISIX

Create an APISIX configuration file in /opt (or directory of your choice):

echo '
apisix:
  ssl:
    ssl_trusted_certificate: /usr/local/apisix/certs/ca.crt
deployment:
  admin:
    admin_key_required: true
    admin_key:
      -
        name: admin
        key: Sup3rs3cretWr1teK3y   # replace with your write key
        role: admin
    admin_listen:
      port: 9180
    https_admin: true
    admin_api_mtls:
      admin_ssl_cert: /usr/local/apisix/certs/admin_api.crt
      admin_ssl_cert_key: /usr/local/apisix/certs/admin_api.key
      admin_ssl_ca_cert: /usr/local/apisix/certs/ca.crt
' > /opt/config.yaml

❶ Set the path to the trusted CA certificate in the Docker container.

❷ Set the listening address for Admin API.

❸ Require TLS for accessing Admin API.

❹ Set the path to the client TLS certificate in the Docker container.

❺ Set the path to the client TLS key in the Docker container.

❻ Set the path to the CA certificate in the Docker container.

Start an APISIX instance in Docker:

docker run -d \
  --name apisix \
  --network host \
  -e APISIX_DEPLOYMENT_ETCD_HOST=https://127.0.0.1:2379 \
  -v /opt/mtls-apisix-admin-api:/usr/local/apisix/certs \
  -v /opt/config.yaml:/usr/local/apisix/conf/config.yaml \
  apache/apisix

❶ Mount the TLS certificate and key directory on host to Docker container.

❷ Mount the APISIX configuration file on host to Docker container.

Verify mTLS

To verify APISIX is up and mTLS is properly configured for Admin API, send a request to get all routes:

curl -ik --resolve "test.com:9180:127.0.0.1" "https://test.com:9180/apisix/admin/routes" \
  --cert client.crt --key client.key \
  -H "X-API-KEY: Sup3rs3cretWr1teK3y"

If everything is ok, you should see a HTTP/1.1 200 OK response with all the APISIX routes, such as:

{"list":[],"total":0}