配置客户端和 APISIX 之间的双向 TLS
双向 TLS(mTLS) 要求客户端和服务器相互验证身份。它通常用于防止未经授权的访问并加强安全性。
本指南将向你展示如何在下游客户端应用程序和 APISIX 之间配置 mTLS。

前置条件
- 安装 Docker。
- 安装支持分别读取 PEM 格式客户端证书和密钥的 curl。下文命令采用 PEM 文件流程。使用 Schannel 后端时,需要改用证书存储路径。
- 按照 快速入门教程 在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。
- 安装 jq 将 PEM 文件编码为 JSON 字符串。
- 如果使用 Admin API 示例且启用了身份验证,请将管理员角色的密钥导出为
ADMIN_API_KEY。请在deployment.admin.admin_key下配置该密钥。Docker 快速入门为了便于本地评估而禁用了身份验证;生产环境中请保持启用。
创建路由
创建一个将所有发往 /ip 的请求转发到上游 httpbin.org 的路由:
curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "quickstart-ip",
"uri": "/ip",
"upstream": {
"nodes": {
"httpbin.org:80":1
},
"type": "roundrobin"
}
}'
生成证书和密钥
生成证书颁发机构 (CA) 密钥和证书:
openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 36500 -sha256 \
-key ca.key \
-out ca.crt \
-subj "/CN=MyTestCA" \
-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 server.key 2048
openssl req -new -sha256 \
-key server.key \
-out server.csr \
-subj "/CN=test.com"
使用 CA 证书对服务器 CSR 进行签名以生成服务器证书:
openssl x509 -req -days 36500 -sha256 \
-in server.csr \
-CA ca.crt -CAkey ca.key -CAcreateserial \
-out server.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")
为 APISIX 配置 mTLS
创建 SSL 对象,并将 SNI 设置为与服务器证书的 test.com DNS 名称匹配。jq 会读取服务器证书、私钥和 CA 证书,并将其中的换行符编码为有效 JSON:
jq -n --rawfile cert server.crt --rawfile key server.key --rawfile ca ca.crt \
'{id: "quickstart-mtls-client-ssl", sni: "test.com", cert: $cert, key: $key, client: {ca: $ca}}' \
| curl -i "http://127.0.0.1:9180/apisix/admin/ssls" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-H "Content-Type: application/json" \
--data-binary @-
client.ca 字段指定 APISIX 在验证客户端证书时信任的 CA。