Skip to content

Latest commit

 

History

History
210 lines (160 loc) · 6.42 KB

mtls.md

File metadata and controls

210 lines (160 loc) · 6.42 KB
Raw
title keywords description
Mutual TLS Authentication
Apache APISIX
Mutual TLS
mTLS
This document describes how you can secure communication to and within APISIX with mTLS.

Protect Admin API

Why use it

Mutual TLS authentication provides a better way to prevent unauthorized access to APISIX.

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 conf/config.yaml:

  admin_listen:
    ip: 127.0.0.1
    port: 9180
  https_admin: true

  admin_api_mtls:
    admin_ssl_ca_cert: "/data/certs/mtls_ca.crt"              # Path of your self-signed ca cert.
    admin_ssl_cert: "/data/certs/mtls_server.crt"             # Path of your self-signed server side cert.
    admin_ssl_cert_key: "/data/certs/mtls_server.key"         # Path of your self-signed server side key.
  1. Run command:
apisix init
apisix reload

How client calls

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 *
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'

etcd with mTLS

How to configure

You need to configure etcd.tls for APISIX to work on an etcd cluster with mTLS enabled as shown below:

deployment:
  role: traditional
  role_traditional:
    config_provider: etcd
  etcd:
    tls:
      cert: /data/certs/etcd_client.pem       # path of certificate used by the etcd client
      key: /data/certs/etcd_client.key        # path of key used by the etcd client

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

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

Protect Route

Why use it

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.

  • Note: the mTLS protection only happens in HTTPS. If your route can also be accessed via HTTP, you should add additional protection in HTTP or disable the access via HTTP.*

How to configure

We provide a tutorial that explains in detail how to configure mTLS between the client and APISIX.

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 Admin API for details.

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

#!/usr/bin/env python
# coding: utf-8
import sys
# sudo pip install requests
import requests

if len(sys.argv) < 4:
    print("bad argument")
    sys.exit(1)
with open(sys.argv[1]) as f:
    cert = f.read()
with open(sys.argv[2]) as f:
    key = f.read()
sni = sys.argv[3]
api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it

reqParam = {
    "cert": cert,
    "key": key,
    "snis": [sni],
}
if len(sys.argv) >= 5:
    print("Setting mTLS")
    reqParam["client"] = {}
    with open(sys.argv[4]) as f:
        clientCert = f.read()
        reqParam["client"]["ca"] = clientCert
    if len(sys.argv) >= 6:
        reqParam["client"]["depth"] = int(sys.argv[5])
resp = requests.put("http://127.0.0.1:9180/apisix/admin/ssls/1", json=reqParam, headers={
    "X-API-KEY": api_key,
})
print(resp.status_code)
print(resp.text)

Create SSL:

./create-ssl.py ./server.pem ./server.key 'mtls.test.com' ./client_ca.pem 10

# test it
curl --resolve 'mtls.test.com:<APISIX_HTTPS_PORT>:<APISIX_URL>' "https://<APISIX_URL>:<APISIX_HTTPS_PORT>/hello" -k --cert ./client.pem --key ./client.key

Please make sure that the SNI fits the certificate domain.

mTLS Between APISIX and Upstream

Why use it

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 Admin API for details.

This feature requires APISIX to run on APISIX-Base.

Here is a similar Python script to patch a existed upstream with mTLS (changes admin API url if needed):

#!/usr/bin/env python
# coding: utf-8
import sys
# sudo pip install requests
import requests

if len(sys.argv) < 4:
    print("bad argument")
    sys.exit(1)
with open(sys.argv[2]) as f:
    cert = f.read()
with open(sys.argv[3]) as f:
    key = f.read()
id = sys.argv[1]
api_key = "edd1c9f034335f136f87ad84b625c8f1" # Change it

reqParam = {
    "tls": {
        "client_cert": cert,
        "client_key": key,
    },
}

resp = requests.patch("http://127.0.0.1:9180/apisix/admin/upstreams/"+id, json=reqParam, headers={
    "X-API-KEY": api_key,
})
print(resp.status_code)
print(resp.text)

Patch existed upstream with id testmtls:

./patch_upstream_mtls.py testmtls ./client.pem ./client.key