跳到主要内容

配置客户端和 APISIX Admin API 之间的 mTLS

双向 TLS (mTLS) 是一种双向 TLS，其中客户端和服务器相互验证身份。它通常用于防止未经授权的访问并加强安全性。

本文档将向你展示如何使用 Docker 化的 APISIX 配置客户端和 APISIX Admin API 之间的 mTLS。对于不同的部署方法，请相应调整步骤。

前置条件​

  • 安装 Docker。
  • 安装 cURL 以向服务发送请求进行验证。

生成证书和密钥​

创建一个新目录并进入其中：

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

生成证书颁发机构 (CA) 密钥和证书：

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")

生成密钥和证书签名请求（CSR）：

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

使用 CA 证书签署服务器 CSR，生成服务器证书：

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\nsubjectAltName=DNS:test.com")

为客户端生成密钥和证书签名请求（CSR）：

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

使用 CA 证书签署客户端 CSR，生成客户端证书：

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")

允许对目录中的文件进行读取访问，以避免下游权限问题：

chmod -R a+r ./

将证书和密钥复制到 /opt/mtls-apisix-admin-api（或你选择的目录）：

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

配置 mTLS​

你将在 Docker 容器中启动 APISIX，并带有 TLS 证书和密钥，以启用与客户端的 mTLS 通信。

为容器创建 Docker 网络：

docker network create mtls-admin-net

启动 etcd​

在 Docker 中启动 etcd 服务器：

docker run -d \
  --name mtls-admin-etcd \
  --network mtls-admin-net \
  gcr.io/etcd-development/etcd:v3.5.32 \
  /usr/local/bin/etcd \
  --name mtls-admin-etcd \
  --data-dir /etcd-data \
  --listen-client-urls http://0.0.0.0:2379 \
  --advertise-client-urls http://mtls-admin-etcd:2379 \
  --listen-peer-urls http://0.0.0.0:2380 \
  --initial-advertise-peer-urls http://mtls-admin-etcd:2380 \
  --initial-cluster mtls-admin-etcd=http://mtls-admin-etcd:2380

启动 APISIX​

在 /opt（或你选择的目录）中创建一个 APISIX 配置文件：

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   # 请替换为你的写入密钥
        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

❶ 在 Docker 容器中设置可信任 CA 证书的路径。

❷ 允许从测试客户端的 IP 地址访问 Admin API。请在生产环境中将 0.0.0.0/0 替换为限制更严格的 CIDR 范围。

❸ 设置 Admin API 的监听地址。

❹ 需要使用 TLS 访问 Admin API。

❺ 在 Docker 容器中设置服务器 TLS 证书的路径。

❻ 在 Docker 容器中设置服务器 TLS 密钥的路径。

❼ 在 Docker 容器中设置 CA 证书的路径。

在 Docker 中启动一个 APISIX 实例：

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.17.0-ubuntu

❶ 将主机上的 TLS 证书和密钥目录挂载到 Docker 容器。

❷ 将主机上的 APISIX 配置文件挂载到 Docker 容器。

验证 mTLS​

要验证 APISIX 是否已启动且客户端和 APISIX Admin API 之间的 mTLS 已正确配置，请向 APISIX 发送请求以获取所有路由：

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

如果成功，你应该看到包含所有 APISIX 路由的 HTTP/1.1 200 OK 响应，例如：

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

如果省略客户端证书和密钥，请求应失败并返回类似 400 Bad Request 的响应：

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