跳到主要内容
版本:3.20.0

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

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

本文介绍如何在客户端与 APISIX Admin API 之间配置 mTLS,使只有通过身份验证的客户端才能通过 Admin API 管理 APISIX 资源。

前置条件​

  • 安装 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")

妥善保护 CA 签名密钥和客户端私钥。仅将 APISIX 运行所需的文件复制到固定版本 Ubuntu 镜像的 apisix 用户(UID 和 GID 均为 636)可访问的目录:

chmod 600 ca.key admin_api.key client.key
sudo install -d -o root -g 636 -m 750 /opt/mtls-apisix-admin-api
sudo install -m 644 ca.crt admin_api.crt /opt/mtls-apisix-admin-api
sudo install -o 636 -g 636 -m 640 admin_api.key /opt/mtls-apisix-admin-api

如果使用其他镜像或运行用户,请将 UID 和 GID 636 替换为对应身份。客户端证书和私钥留在当前目录,供验证请求使用,不挂载到 APISIX 容器中。

配置 mTLS​

你将在 Docker 容器中启动 etcd 和 APISIX,并配置 APISIX,以便 Admin API 使用 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 # 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

❶ 在 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:ro \
-v /opt/config.yaml:/usr/local/apisix/conf/config.yaml:ro \
apache/apisix:3.20.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>
...