跳到主要内容
版本:3.20.0

配置客户端和 APISIX 之间的双向 TLS

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

本指南将向你展示如何在下游客户端应用程序和 APISIX 之间配置 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。

验证客户端和 APISIX 之间的 mTLS​

使用客户端证书​

服务器证书对 DNS 名称 test.com 有效。验证时使用该主机名,同时将其解析到本地 APISIX 地址。

携带客户端证书发送请求。--cacert 验证 APISIX 的证书链,--resolve 将 test.com 连接到 127.0.0.1,同时保留主机名验证:

curl -iv --cacert ca.crt \
--noproxy test.com \
--resolve "test.com:9443:127.0.0.1" \
--cert client.crt \
--key client.key \
"https://test.com:9443/ip"

请求应成功,并返回 HTTP 2xx 响应。使用 OpenSSL 后端的 curl 时,相关输出应类似于:

* subjectAltName: host "test.com" matched cert's "test.com"
* SSL certificate verify ok.
< HTTP/2 200

完整输出会随 curl 的 TLS 后端和协商的 HTTP 版本而变化。应确认输出同时表明证书主机名匹配且证书验证成功,不要只依据 HTTP 状态判断。

这验证了 mTLS 的双方:curl 信任并验证 APISIX 的证书,而 APISIX 请求并接受客户端证书。

不使用客户端证书​

保留相同的服务器证书验证,但不提供客户端证书和私钥,再次发送请求:

curl -iv --cacert ca.crt \
--noproxy test.com \
--resolve "test.com:9443:127.0.0.1" \
"https://test.com:9443/ip"

前一次成功请求已经确认服务器证书和主机名通过验证。由于这次未提供客户端证书,APISIX 应拒绝请求。使用 OpenSSL 后端的 curl 时,拒绝结果可能类似于:

curl: (56) OpenSSL SSL_read: ... tlsv13 alert certificate required

根据 APISIX 运行时及 curl 的 TLS 后端,curl 也可能收到 HTTP 400 Bad Request 响应。

使用不受信任 CA 签发的客户端证书​

生成第二个 CA,以及 APISIX 不信任的客户端证书:

openssl genrsa -out untrusted-ca.key 2048
openssl req -new -x509 -days 36500 -sha256 \
-key untrusted-ca.key \
-out untrusted-ca.crt \
-subj "/CN=UntrustedClientCA" \
-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")

openssl genrsa -out untrusted-client.key 2048
openssl req -new -sha256 \
-key untrusted-client.key \
-out untrusted-client.csr \
-subj "/CN=UNTRUSTED_CLIENT"
openssl x509 -req -days 36500 -sha256 \
-in untrusted-client.csr \
-CA untrusted-ca.crt -CAkey untrusted-ca.key -CAcreateserial \
-out untrusted-client.crt \
-extensions v3_req \
-extfile <(printf "[v3_req]\nbasicConstraints=CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=clientAuth")

发送请求时仍用 ca.crt 验证 APISIX 服务器,但提供不受信任的客户端证书:

curl -iv --cacert ca.crt \
--noproxy test.com \
--resolve "test.com:9443:127.0.0.1" \
--cert untrusted-client.crt \
--key untrusted-client.key \
"https://test.com:9443/ip"

前一次成功请求已经确认服务器证书和主机名通过验证。由于客户端证书不属于配置的信任链,APISIX 应拒绝请求。使用 OpenSSL 后端的 curl 时,拒绝结果可能类似于:

curl: (56) OpenSSL SSL_read: ... tlsv1 alert unknown ca

根据 APISIX 运行时及 curl 的 TLS 后端,curl 也可能收到 HTTP 400 Bad Request 响应。

对其他主机复用 HTTP/2 连接​

HTTP/2 客户端可以将现有 TLS 连接复用于服务器证书涵盖的另一个来源。当选中的 SSL 对象要求客户端证书时,APISIX 会比较请求 Host 和连接使用的 SNI。如果两者不同,APISIX 返回 421 Misdirected Request,以便客户端使用预期的 SNI 和客户端证书在新连接上重试。

TLS 握手失败会在 APISIX 到达此访问阶段检查前结束请求。在正常的访问路径上,APISIX 会先比较 Host 和 SNI,再检查客户端证书。如果连接的 SSL 对象配置了 skip_mtls_uri_regex 且该 URI 未获豁免,APISIX 会先检查证书,因此可能在比较 Host 和 SNI 之前返回 400 Bad Request。

为选定 URI 跳过 mTLS​

当健康检查等少量端点必须允许不带客户端证书访问时,请在 SSL 对象上设置 client.skip_mtls_uri_regex。每个值都是与请求 URI 匹配的 PCRE 正则表达式。

使用豁免模式更新现有 SSL 对象:

curl -i "http://127.0.0.1:9180/apisix/admin/ssls/quickstart-mtls-client-ssl" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"client": {
"skip_mtls_uri_regex": [
"^/health$",
"^/open(?:/|%2F).*"
]
}
}'

❶ 仅豁免 /health。

❷ 豁免 /open/ 下的路径,包括启用编码斜杠路由时的 /open%2Ffoo 等编码边界。其他路径仍需要受信任的客户端证书。

有关豁免必须涵盖的两种 URI 形式,请参阅在参数中匹配编码斜杠。

下一步​

你可以在 SSL 证书 中了解更多关于 mTLS 和 APISIX SSL 对象的信息。

APISIX 还支持客户端和 APISIX 之间的 TLS 连接。有关更多详细信息,请参阅 配置客户端和 APISIX 之间的 HTTPS。