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

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

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

前置条件

安装 Docker。
安装 cURL 以向服务发送请求进行验证。
按照快速入门教程在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。

创建路由

创建一个将所有请求 /ip 转发到上游 httpbin.org 的路由：

Admin API
Ingress Controller

curl -i "http://127.0.0.1:9180/apisix/admin/routes" -X PUT -d '
{
  "id": "quickstart-ip",
  "uri": "/ip",
  "upstream": {
    "nodes": {
      "httpbin.org:80":1
    },
    "type": "roundrobin"
  }
}'

Gateway API
APISIX CRD

APISIX Ingress Controller 目前不支持使用 Gateway API 配置客户端和 APISIX 之间的 mTLS。

httpbin-route.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
  namespace: ingress-apisix
  name: httpbin-external-domain
spec:
  ingressClassName: apisix
  externalNodes:
  - type: Domain
    name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: ingress-apisix
  name: quickstart-ip
spec:
  ingressClassName: apisix
  http:
    - name: quickstart-ip
      match:
        paths:
          - /ip
      upstreams:
      - name: httpbin-external-domain

将配置应用到你的集群：

kubectl apply -f httpbin-route.yaml

生成证书和密钥

生成证书颁发机构 (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

你可以选择将 server.crt、server.key 和 ca.crt 的内容加载到环境变量中：

export server_cert=$(cat server.crt)
export server_key=$(cat server.key)
export ca_cert=$(cat ca.crt)

Admin API
ADC
Ingress Controller

创建一个 SSL 证书对象以保存服务器证书、服务器证书密钥和 CA 证书：

curl -i "http://127.0.0.1:9180/apisix/admin/ssls" -X PUT -d '
{
  "id": "quickstart-mtls-client-ssl",
// Annotate 1
  "sni": "test.com",
// Annotate 2
  "cert": "'"${server_cert}"'",
// Annotate 3
  "key": "'"${server_key}"'",
  "client": {
// Annotate 4
    "ca": "'"${ca_cert}"'"
  }
}'

❶ sni：test.com，与服务器证书 CN 值相同

❷ cert：服务器证书 server.crt

❸ key：服务器证书密钥 server.key

❹ client.ca：CA 证书 ca.crt

important

如果你尚未启用网关的 SSL，请启用它：

helm upgrade apisix apisix/apisix \
  --namespace ingress-apisix \
  --set apisix.deployment.role=traditional \
  --set apisix.deployment.role_traditional.config_provider=yaml \
  --set etcd.enabled=false \
  --set ingress-controller.enabled=true \
  --set ingress-controller.config.provider.type=apisix-standalone \
  --set ingress-controller.apisix.adminService.namespace=ingress-apisix \
  --set ingress-controller.gatewayProxy.createDefault=true \
  --set apisix.ssl.enabled=true

将 SSL 端口转发到你的主机：

kubectl port-forward svc/apisix-gateway 9443:443 &

Gateway API
APISIX CRD

APISIX Ingress Controller 目前不支持使用 Gateway API 配置客户端和 APISIX 之间的 mTLS。

创建两个 Kubernetes secrets：

kubectl create secret tls test-mtls-secret \
  --cert=server.crt \
  --key=server.key \
  --namespace=ingress-apisix

kubectl create secret generic test-ca-secret \
  --from-file=cert=ca.crt \
  --namespace=ingress-apisix

为 mTLS 配置创建一个 Kubernetes 清单文件：

mtls.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixTls
metadata:
  namespace: ingress-apisix
  name: test-mtls
spec:
  ingressClassName: apisix
  hosts:
    - test.com
  secret:
    name: test-mtls-secret
    namespace: ingress-apisix
  client:
    caSecret:
      name: test-ca-secret
      namespace: ingress-apisix
    depth: 1

将配置应用到你的集群：

kubectl apply -f mtls.yaml

验证客户端和 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​

使用客户端证书​

不使用客户端证书​

下一步​