TLS 双向认证

保护 Admin API

为什么使用

双向认证提供了一种更好的方法来阻止未经授权的对 APISIX Admin API 的访问。

客户端需要向服务器提供证书,服务器将检查该客户端证书是否由受信的 CA 签名,并决定是否响应其请求。

如何配置

  1. 生成自签证书对,包括 CA、server、client 证书对。

  2. 修改 conf/config.yaml 中的配置项:

conf/config.yaml

  1. admin_listen:
  2. ip: 127.0.0.1
  3. port: 9180
  4. https_admin: true
  5. admin_api_mtls:
  6. admin_ssl_ca_cert: "/data/certs/mtls_ca.crt" # Path of your self-signed ca cert.
  7. admin_ssl_cert: "/data/certs/mtls_server.crt" # Path of your self-signed server side cert.
  8. admin_ssl_cert_key: "/data/certs/mtls_server.key" # Path of your self-signed server side key.
  1. 执行命令,使配置生效:
  1. apisix init
  2. apisix reload

客户端如何调用

需要将证书文件的路径与域名按实际情况替换。

  • 注意:提供的 CA 证书需要与服务端的相同。*
  1. curl --cacert /data/certs/mtls_ca.crt --key /data/certs/mtls_client.key --cert /data/certs/mtls_client.crt https://admin.apisix.dev:9180/apisix/admin/routes -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

保护 ETCD

如何配置

你需要构建 APISIX-runtime,并且需要在配置文件中设定 etcd.tls 来使 ETCD 的双向认证功能正常工作。

conf/config.yaml

  1. deployment:
  2. role: traditional
  3. role_traditional:
  4. config_provider: etcd
  5. etcd:
  6. tls:
  7. cert: /data/certs/etcd_client.pem # path of certificate used by the etcd client
  8. key: /data/certs/etcd_client.key # path of key used by the etcd client

如果 APISIX 不信任 etcd server 使用的 CA 证书,我们需要设置 CA 证书。

conf/config.yaml

  1. apisix:
  2. ssl:
  3. ssl_trusted_certificate: /path/to/certs/ca-certificates.crt # path of CA certificate used by the etcd server

保护路由

为什么使用

双向认证是一种密码学安全的验证客户端身份的手段。当你需要加密并保护流量的双向安全时很有用。

  • 注意:双向认证只发生在 HTTPS 中。如果你的路由也可以通过 HTTP 访问,你应该在 HTTP 中添加额外的保护,或者禁止通过 HTTP 访问。*

如何配置

我们提供了一个演示教程,详细地讲解了如何配置客户端和 APISIX 之间的 mTLS。

在配置 ssl 资源时,同时需要配置 client.caclient.depth 参数,分别代表为客户端证书签名的 CA 列表,和证书链的最大深度。可参考:SSL API 文档

下面是一个可用于生成带双向认证配置的 SSL 资源的 shell 脚本示例(如果需要,可修改 API 地址、API Key 和 SSL 资源的 ID。):

  1. curl http://127.0.0.1:9180/apisix/admin/ssls/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. "cert": "'"$(cat t/certs/mtls_server.crt)"'",
  4. "key": "'"$(cat t/certs/mtls_server.key)"'",
  5. "snis": [
  6. "admin.apisix.dev"
  7. ],
  8. "client": {
  9. "ca": "'"$(cat t/certs/mtls_ca.crt)"'",
  10. "depth": 10
  11. }
  12. }'

测试:

  1. curl -vvv --resolve 'admin.apisix.dev:9443:127.0.0.1' https://admin.apisix.dev:9443/hello --cert t/certs/mtls_client.crt --key t/certs/mtls_client.key --cacert t/certs/mtls_ca.crt
  2. * Added admin.apisix.dev:9443:127.0.0.1 to DNS cache
  3. * Hostname admin.apisix.dev was found in DNS cache
  4. * Trying 127.0.0.1:9443...
  5. * Connected to admin.apisix.dev (127.0.0.1) port 9443 (#0)
  6. * ALPN: offers h2
  7. * ALPN: offers http/1.1
  8. * CAfile: t/certs/mtls_ca.crt
  9. * CApath: none
  10. * [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, Client hello (1):
  11. * [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Server hello (2):
  12. * [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Unknown (8):
  13. * [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Request CERT (13):
  14. * [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Certificate (11):
  15. * [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, CERT verify (15):
  16. * [CONN-0-0][CF-SSL] (304) (IN), TLS handshake, Finished (20):
  17. * [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, Certificate (11):
  18. * [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, CERT verify (15):
  19. * [CONN-0-0][CF-SSL] (304) (OUT), TLS handshake, Finished (20):
  20. * SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384
  21. * ALPN: server accepted h2
  22. * Server certificate:
  23. * subject: C=cn; ST=GuangDong; L=ZhuHai; CN=admin.apisix.dev; OU=ops
  24. * start date: Dec 1 10:17:24 2022 GMT
  25. * expire date: Aug 18 10:17:24 2042 GMT
  26. * subjectAltName: host "admin.apisix.dev" matched cert's "admin.apisix.dev"
  27. * issuer: C=cn; ST=GuangDong; L=ZhuHai; CN=ca.apisix.dev; OU=ops
  28. * SSL certificate verify ok.
  29. * Using HTTP2, server supports multiplexing
  30. * Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
  31. * h2h3 [:method: GET]
  32. * h2h3 [:path: /hello]
  33. * h2h3 [:scheme: https]
  34. * h2h3 [:authority: admin.apisix.dev:9443]
  35. * h2h3 [user-agent: curl/7.87.0]
  36. * h2h3 [accept: */*]
  37. * Using Stream ID: 1 (easy handle 0x13000bc00)
  38. > GET /hello HTTP/2
  39. > Host: admin.apisix.dev:9443
  40. > user-agent: curl/7.87.0
  41. > accept: */*

注意,测试时使用的域名需要符合证书的参数。

APISIX 与上游间的双向认证

为什么使用

有时候上游的服务启用了双向认证。在这种情况下,APISIX 作为上游服务的客户端,需要提供客户端证书来正常与其进行通信。

如何配置

在配置 upstream 资源时,可以使用参数 tls.client_certtls.client_key 来配置 APISIX 用于与上游进行通讯时使用的证书。可参考 Upstream API 文档

该功能需要 APISIX 运行在 APISIX-Runtime 上。

下面是一个与配置 SSL 时相似的 shell 脚本,可为一个已存在的 upstream 资源配置双向认证。

  1. curl http://127.0.0.1:9180/apisix/admin/upstreams/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PATCH -d '
  3. {
  4. "tls": {
  5. "client_cert": "'"$(cat t/certs/mtls_client.crt)"'",
  6. "client_key": "'"$(cat t/certs/mtls_client.key)"'"
  7. }
  8. }'