版本：3.19.0

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

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

本指南将向你展示如何在下游客户端应用程序和 APISIX 之间配置 mTLS。

前置条件

安装 Docker。
安装 cURL 以向服务发送请求进行验证。
按照快速入门教程在 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")

为客户端生成密钥和证书签名请求 (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 匹配。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

使用客户端证书

由于证书仅对 CN test.com 有效，你应该使用 test.com 作为托管 APISIX 的域名。

向 https://test.com:9443/ip 发送请求，带上客户端证书，并将 test.com 解析为 127.0.0.1：

curl -ikv --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/ip" \
  --cert client.crt --key client.key

类似于以下的 mTLS 握手过程验证了客户端和 APISIX 之间的 mTLS 已启用：

* Added test.com:9443:127.0.0.1 to DNS cache
* Hostname test.com was found in DNS cache
*   Trying 127.0.0.1:9443...
* Connected to test.com (127.0.0.1) port 9443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
*  CAfile: /etc/ssl/certs/ca-certificates.crt
*  CApath: /etc/ssl/certs
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
* TLSv1.3 (IN), TLS handshake, Request CERT (13):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
* TLSv1.3 (IN), TLS handshake, Finished (20):
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.3 (OUT), TLS handshake, Certificate (11):
* TLSv1.3 (OUT), TLS handshake, CERT verify (15):
* TLSv1.3 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
* ALPN, server accepted to use h2
* Server certificate:
*  subject: CN=test.com
*  start date: Apr 21 07:47:54 2023 GMT
*  expire date: Mar 28 07:47:54 2123 GMT
*  issuer: CN=ROOTCA
*  SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
* Using HTTP2, server supports multi-use
* Connection state changed (HTTP/2 confirmed)
* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
* Using Stream ID: 1 (easy handle 0x5625339a72e0)
> GET /ip HTTP/2
> Host: test.com:9443
> user-agent: curl/7.74.0
> accept: */*
>
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* old SSL session ID is stale, removing
* Connection state changed (MAX_CONCURRENT_STREAMS == 128)!
< HTTP/2 200
HTTP/2 200
...

请注意，APISIX 和客户端在握手过程中成功验证了彼此的证书并建立了连接。

不使用客户端证书

向 https://test.com:9443/ip 发送请求但不带客户端证书：

curl -ikv --resolve "test.com:9443:127.0.0.1" "https://test.com:9443/ip"

失败的 mTLS 握手类似于以下内容：

* Added test.com:9443:127.0.0.1 to DNS cache
* Hostname test.com was found in DNS cache
*   Trying 127.0.0.1:9443...
* Connected to test.com (127.0.0.1) port 9443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
*  CAfile: /etc/ssl/certs/ca-certificates.crt
*  CApath: /etc/ssl/certs
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
* TLSv1.3 (IN), TLS handshake, Request CERT (13):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
* TLSv1.3 (IN), TLS handshake, Finished (20):
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.3 (OUT), TLS handshake, Certificate (11):
* TLSv1.3 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
* ALPN, server accepted to use h2
* Server certificate:
*  subject: CN=test.com
*  start date: Apr 21 07:47:54 2023 GMT
*  expire date: Mar 28 07:47:54 2123 GMT
*  issuer: CN=ROOTCA
*  SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway.
* Using HTTP2, server supports multi-use
* Connection state changed (HTTP/2 confirmed)
* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
* Using Stream ID: 1 (easy handle 0x55f791e252e0)
> GET /ip HTTP/2
> Host: test.com:9443
> user-agent: curl/7.74.0
> accept: */*
>
* TLSv1.3 (IN), TLS alert, unknown (628):
* OpenSSL SSL_read: error:1409445C:SSL routines:ssl3_read_bytes:tlsv13 alert certificate required, errno 0
* Failed receiving HTTP2 data
* OpenSSL SSL_write: SSL_ERROR_ZERO_RETURN, errno 0
* Failed sending HTTP2 data
* Connection #0 to host test.com left intact

由于缺少客户端证书，握手失败。

下一步

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

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

前置条件​

创建路由​

生成证书和密钥​

为 APISIX 配置 mTLS​

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

使用客户端证书​

不使用客户端证书​

下一步​