配置 API7 企业版与上游之间的 mTLS
双向 TLS(mTLS)让客户端和服务器相互验证身份。它通常用于安全要求较高的环境,以防止未经授权的访问并增强安全性。
本指南以 NGINX 为上游服务示例,介绍如何配置 APISIX 与上游服务之间的 mTLS。
你可以通过下面的交互式演示体验配置过程。
前提条件
- 安装 API7 企业版。
- 创建你的第一个 API。
- 在 API7 企业版中创建一个 Token。
生成证书和密钥
-
生成证书颁发机构(CA)的密钥和证书。
openssl genrsa -out ca.key 2048openssl req -x509 -new -nodes -key ca.key -sha256 -days 36500 -out ca.crt \-subj "/CN=ROOTCA" -
为 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 << EOFauthorityKeyIdentifier=keyid,issuerbasicConstraints=CA:FALSEkeyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEnciphermentsubjectAltName = @alt_names[alt_names]DNS.1 = test.comEOFopenssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \-CAcreateserial -out server.crt -days 36500 \-sha256 -extfile server.ext -
生成客户端密钥和公用名为
CLIENT的客户端证书,并使用 CA 证书签名。openssl genrsa -out client.key 2048 && \openssl req -new -key client.key -out client.csr -subj "/CN=client" && \cat > client.ext << EOFauthorityKeyIdentifier=keyid,issuerbasicConstraints=CA:FALSEkeyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEnciphermentextendedKeyUsage = clientAuthEOFopenssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 36500 -sha256 -extfile client.ext -
生成证书和密钥后,在本地设备上找到以下文件。
❶
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 请求。
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 服务器的路由
- 登录 API7 企业版控制台,选择
default网关组。 - 创建名为
mtls-nginx的服务和一条路径为/hello、方法为GET的路由。 - 为该服务配置上游节点。在 主机 字段中输入 API7 控制台的 IP 地址,并将 端口 字段设为
8443。 - 在 协议 字段中选择
HTTPS。
配置 SSL 证书
-
在侧边栏中选择 SSL 证书,然后点击 + 新增 SSL 证书。
-
在 + 新增 SSL 证书 对话框中完成以下操作。
- 在 类型 字段中选择
客户端证书。 - 选择 上传 方式。
- 在 证书 字段中上传
client.crt文件。 - 在 私钥 字段中上传
client.key文件。 - 启用 对等验证。
- 在 CA 证书(可选) 字段中上传
ca.crt文件。 - 点击 新增。
- 在 类型 字段中选择
-
添加成功后,这张 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 已配置成功。
相关阅读
- 核心概念
- 快速入门