Mutual TLS Authentication

    The clients will provide their certificates to the server and the server will check whether the cert is signed by the supplied CA and decide whether to serve the request.

    How to configure

    1. Generate self-signed key pairs, including ca, server, client key pairs.

    2. Modify configuration items in :

    1. Run command:
    1. apisix init
    2. apisix reload

    Please replace the following certificate paths and domain name with your real ones.

    • Note: The same CA certificate as the server needs to be used *
    1. curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt  https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

    How to configure

    If APISIX does not trust the CA certificate that used by etcd server, we need to set up the CA certificate.

    1. apisix:
    2.   ssl:
    3.     ssl_trusted_certificate: /path/to/certs/ca-certificates.crt       # path of CA certificate used by the etcd server

    Using mTLS is a way to verify clients cryptographically. It is useful and important in cases where you want to have encrypted and secure traffic in both directions.

    How to configure

    When configuring ssl, use parameter client.ca and client.depth to configure the root CA that signing client certificates and the max length of certificate chain. Please refer to for details.

    Here is an example Python script to create SSL with mTLS (id is 1, changes admin API url if needed):

    1. #!/usr/bin/env python
    2. # coding: utf-8
    3. # save this file as ssl.py
    4. import sys
    5. # sudo pip install requests
    6. import requests
    7. if len(sys.argv) < 4:
    8.     print("bad argument")
    9.     sys.exit(1)
    10. with open(sys.argv[1]) as f:
    11.     cert = f.read()
    12. with open(sys.argv[2]) as f:
    13.     key = f.read()
    14. sni = sys.argv[3]
    17. reqParam = {
    18.     "cert": cert,
    19.     "key": key,
    20.     "snis": [sni],
    21. }
    22. if len(sys.argv) >= 5:
    23.     print("Setting mTLS")
    24.     reqParam["client"] = {}
    25.     with open(sys.argv[4]) as f:
    26.         clientCert = f.read()
    27.         reqParam["client"]["ca"] = clientCert
    28.     if len(sys.argv) >= 6:
    29.         reqParam["client"]["depth"] = int(sys.argv[5])
    30. resp = requests.put("http://127.0.0.1:9080/apisix/admin/ssl/1", json=reqParam, headers={
    31.     "X-API-KEY": api_key,
    32. })
    33. print(resp.status_code)
    34. print(resp.text)

    Please make sure that the SNI fits the certificate domain.

    Sometimes the upstream requires mTLS. In this situation, the APISIX acts as the client, it needs to provide client certificate to communicate with upstream.

    How to configure

    When configuring upstreams, we could use parameter tls.client_cert and tls.client_key to configure the client certificate APISIX used to communicate with upstreams. Please refer to for details.

    This feature requires APISIX to run on APISIX-Base.

    1. # coding: utf-8
    2. # save this file as patch_upstream_mtls.py
    3. import sys
    5. import requests
    7. if len(sys.argv) < 4:
    8.     print("bad argument")
    9.     sys.exit(1)
    10. with open(sys.argv[2]) as f:
    11.     cert = f.read()
    12. with open(sys.argv[3]) as f:
    13.     key = f.read()
    14. id = sys.argv[1]
    15. api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it
    17. reqParam = {
    18.     "tls": {
    19.         "client_cert": cert,
    20.         "client_key": key,
    21.     },
    22. }
    24. resp = requests.patch("http://127.0.0.1:9080/apisix/admin/upstreams/"+id, json=reqParam, headers={
    25.     "X-API-KEY": api_key,
    26. })
    27. print(resp.status_code)
    28. print(resp.text)

    Patch existed upstream with id testmtls: