跳到主要内容
版本:3.2.16.6

配置 API7 企业版与上游之间的 mTLS

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

本指南以 NGINX 为上游服务示例,介绍如何配置 APISIX 与上游服务之间的 mTLS。

你可以通过下面的交互式演示体验配置过程。

前提条件​

生成证书和密钥​

  1. 生成证书颁发机构(CA)的密钥和证书。

    openssl genrsa -out ca.key 2048
    openssl req -x509 -new -nodes -key ca.key -sha256 -days 36500 -out ca.crt \
    -subj "/CN=ROOTCA"
  2. 为 API7 企业版生成服务器密钥和公用名为 test.com 的服务器证书,并使用 CA 证书签名。

    openssl genrsa -out server.key 2048 && \
    openssl req -new -key server.key -out server.csr -subj "/CN=test.com" && \
    cat > server.ext << EOF
    authorityKeyIdentifier=keyid,issuer
    basicConstraints=CA:FALSE
    keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
    subjectAltName = @alt_names
    [alt_names]
    DNS.1 = test.com
    EOF
    openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
    -CAcreateserial -out server.crt -days 36500 \
    -sha256 -extfile server.ext
  3. 生成客户端密钥和公用名为 CLIENT 的客户端证书,并使用 CA 证书签名。

    openssl genrsa -out client.key 2048 && \
    openssl req -new -key client.key -out client.csr -subj "/CN=client" && \
    cat > client.ext << EOF
    authorityKeyIdentifier=keyid,issuer
    basicConstraints=CA:FALSE
    keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
    extendedKeyUsage = clientAuth
    EOF
    openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 36500 -sha256 -extfile client.ext
  4. 生成证书和密钥后,在本地设备上找到以下文件。

    ❶ client.crt:客户端证书。

    ❷ client.key:客户端证书的密钥。

    ❸ ca.crt:CA 证书。

配置上游服务​

启动 NGINX 服务器作为示例上游服务。

docker run -d \
--name quickstart-nginx \
--network=apisix-quickstart-net \
-p 8443:8443 \
nginx

将 CA 证书、服务器证书及其私钥复制到 NGINX 容器中。

docker cp ca.crt quickstart-nginx:/var/ca.crt
docker cp server.crt quickstart-nginx:/var/server.crt
docker cp server.key quickstart-nginx:/var/server.key

在 NGINX 配置文件中配置一个 HTTPS 服务器,监听 8443 端口并处理 /hello 请求。

/etc/nginx/nginx.conf
user nginx;
worker_processes auto;

error_log /var/log/nginx/error.log notice;
pid /var/run/nginx.pid;


events {
worker_connections 1024;
}


http {
include /etc/nginx/mime.types;
default_type application/octet-stream;

log_format main '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"';

access_log /var/log/nginx/access.log main;

sendfile on;
#tcp_nopush on;

keepalive_timeout 65;

#gzip on;

server {
listen 8443 ssl;
server_name test.com;
ssl_certificate /var/server.crt;
ssl_certificate_key /var/server.key;
ssl_client_certificate /var/ca.crt;
ssl_verify_client on;
location /hello {
return 200 "Hello API7!";
}
}

include /etc/nginx/conf.d/*.conf;
}

❶ server_name:设为 test.com,与服务器证书的 CN 值一致。

❷ ssl_certificate:配置服务器证书公钥 server.crt 的路径。

❸ ssl_certificate_key:配置服务器证书私钥 server.key 的路径。

❹ ssl_client_certificate:配置 CA 证书公钥 ca.crt 的路径。

❺ ssl_verify_client:设为 on,以验证客户端证书。

重新加载 NGINX 服务器以应用配置变更。

docker exec quickstart-nginx nginx -s reload

向路由发送携带客户端证书和密钥的请求,验证 NGINX 实例的配置。

curl -ik "https://127.0.0.1:8443/hello" --cert client.crt --key client.key

你应收到 HTTP/1.1 200 OK 响应。

配置 API7 企业版的 mTLS​

创建指向 NGINX 服务器的路由​

  1. 登录 API7 企业版控制台,选择 default 网关组。
  2. 创建名为 mtls-nginx 的服务和一条路径为 /hello、方法为 GET 的路由。
  3. 为该服务配置上游节点。在 主机 字段中输入 API7 控制台的 IP 地址,并将 端口 字段设为 8443。
  4. 在 协议 字段中选择 HTTPS。

配置 SSL 证书​

  1. 在侧边栏中选择 SSL 证书,然后点击 + 新增 SSL 证书。

  2. 在 + 新增 SSL 证书 对话框中完成以下操作。

    • 在 类型 字段中选择 客户端证书。
    • 选择 上传 方式。
    • 在 证书 字段中上传 client.crt 文件。
    • 在 私钥 字段中上传 client.key 文件。
    • 启用 对等验证。
    • 在 CA 证书(可选) 字段中上传 ca.crt 文件。
    • 点击 新增。
  3. 添加成功后,这张 SSL 证书会带有一个 ID,其 SNIS 为 test.com。

修改上游服务的 TLS 配置​

设置环境变量。

export service_id=${YOUR_SERVICE_ID}
export gateway_group_id=${YOUR_GATEWAY_GROUP_ID}
export client_cert_id=${YOUR_CLIENT_CERT_KEY}
export X_API_KEY=${YOUR_API_KEY}

查看服务配置。

curl -k -X GET "https://192.168.31.29:7443/apisix/admin/services/$service_id?gateway_group_id=$gateway_group_id" \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: ${YOUR_API_KEY}'

你会收到类似的响应,其中没有 TLS 键。

..."service_id":"b7c9c7bc-19b3-47db-b2a2-4867380e2ff1","id":"b7c9c7bc-19b3-47db-b2a2-4867380e2ff1","service_version_id":"5e59b458-e5e3-426e-9f9e-668ced45e522","gateway_group_id":"default","gateway_group_name":"default","status":1,
...

修改上游服务的 TLS 配置。

curl -k -X PATCH "https://192.168.31.29:7443/apisix/admin/services/$service_id?gateway_group_id=$gateway_group_id" \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: ${YOUR_API_KEY}' \
-d '[{"op":"add", "path":"/upstream/tls", "value": {"client_cert_id": ${YOUR_CLIENT_CERT_ID}}}]'

你会收到类似的响应,其中包含 TLS 键。

...
"tls":{"client_cert_id":"58999f7b-3400-493a-a518-99716439488e"}},
"service_id":"b7c9c7bc-19b3-47db-b2a2-4867380e2ff1","id":"b7c9c7bc-19b3-47db-b2a2-4867380e2ff1","service_version_id":"5e59b458-e5e3-426e-9f9e-668ced45e522","gateway_group_id":"default","gateway_group_name":"default","status":1,
...

验证 API7 企业版与上游服务之间的 mTLS​

向路由发送请求。

curl -ik "http://127.0.0.1:9080/hello"

你应收到 HTTP/1.1 200 OK 响应,这表示 API7 企业版与上游服务之间的 mTLS 已配置成功。

相关阅读​