Configure mTLS between Client and APISIX Admin API

Mutual TLS (mTLS) is a two-way TLS where the 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 a 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 -x509 -days 36500 -sha256 \
  -key ca.key \
  -out ca.crt \
  -subj "/CN=ROOTCA" \
  -extensions v3_ca \
  -config <(printf "[req]\ndistinguished_name=req\n[ v3_ca ]\nbasicConstraints=critical,CA:TRUE\nkeyUsage=critical,keyCertSign,cRLSign\nsubjectKeyIdentifier=hash\nauthorityKeyIdentifier=keyid:always,issuer")

Generate the key and certificate signing request (CSR):

openssl genrsa -out admin_api.key 2048
openssl req -new -sha256 \
  -key admin_api.key \
  -out admin_api.csr \
  -subj "/CN=test.com"

Sign the server CSR with the CA certificate to generate the server certificate:

openssl x509 -req -days 36500 -sha256 \
  -in admin_api.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out admin_api.crt \
  -extensions v3_req \
  -extfile <(printf "[v3_req]\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth")

Generate the key and certificate signing request (CSR) for the client:

openssl genrsa -out client.key 2048
openssl req -new -sha256 \
  -key client.key \
  -out client.csr \
  -subj "/CN=CLIENT"

Sign the client CSR with the CA certificate to generate the client certificate:

openssl x509 -req -days 36500 -sha256 \
  -in client.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client.crt \
  -extensions v3_req \
  -extfile <(printf "[v3_req]\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=clientAuth")

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

chmod -R a+r ./

Copy certificates and keys into /opt/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 configuring APISIX to enable mTLS for Admin API.

Create a Docker network for the containers:

docker network create mtls-admin-net

Start etcd

Start an etcd server in Docker:

docker run -d \
  --name mtls-admin-etcd \
  --network mtls-admin-net \
  -e ALLOW_NONE_AUTHENTICATION=yes \
  -e ETCD_ADVERTISE_CLIENT_URLS=http://mtls-admin-etcd:2379 \
  -e ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379 \
  bitnamilegacy/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:
  role: traditional
  role_traditional:
    config_provider: etcd
  admin:
    admin_key_required: true
    allow_admin:
      - 0.0.0.0/0
    admin_key:
      -
        name: admin
        key: Sup3rs3cretWr1teK3y   # replace with your write key
        role: admin
    admin_listen:
      ip: 0.0.0.0
      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
  etcd:
    host:
      - "http://mtls-admin-etcd:2379"
' > /opt/config.yaml

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

❷ Allow Admin API access from your test client IP address. Replace 0.0.0.0/0 with a more restrictive CIDR range in production.

❸ Set the listening address for Admin API.

❹ Require TLS for accessing Admin API.

❺ Set the path to the server TLS certificate in the Docker container.

❻ Set the path to the server 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 mtls-admin-apisix \
  --network mtls-admin-net \
  -p 9180:9180 \
  -v /opt/mtls-apisix-admin-api:/usr/local/apisix/certs \
  -v /opt/config.yaml:/usr/local/apisix/conf/config.yaml \
  apache/apisix:3.16.0-ubuntu

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

❷ Mount the APISIX configuration file on the host to the 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}

If you omit the client certificate and key, the request should fail with a 400 Bad Request response similar to:

<html>
<head><title>400 No required SSL certificate was sent</title></head>
...