Kong API 网关加固实战:管理接口与鉴权收口

Kong API 网关加固的重点不是装插件,而是先回答一个问题:谁能调用管理接口。Kong 开源版的 Admin API 默认监听 8001 且不做任何身份校验,只要该端口可达,任何人都能新增路由、读取消费者密钥、把流量转发到任意上游——这比任何一个业务漏洞都严重。

第二个重点是「谁是真的来源 IP」。Kong 的 ip-restriction、rate-limiting 都依赖客户端地址,而地址来自 X-Forwarded-For。信任链没配好,攻击者自己填一个 X-Forwarded-For: 10.0.0.1 就能同时绕过 IP 白名单和限流。本文按「端口收口 — 信任链校正 — 鉴权限流 — 声明式配置」的顺序落地。

适用场景

  • Kong 作为对外 API 统一入口,后端有多个微服务,需要在一处做鉴权、限流与来源限制
  • 等保或接口安全检查指出「API 无认证」「无调用频次限制」「管理端口对公网开放」
  • 多个合作方共用同一套接口,需要按消费者发放密钥并单独计量配额
  • 出现过来源 IP 判断错误导致白名单失效,或日志里的客户端地址全是同一个网关 IP

前置条件

  • Kong Gateway 3.4 及以上(OSS 版即可,本文不依赖企业版 RBAC)
  • Docker 24+ 与 docker compose v2,或 RPM/DEB 原生部署;数据库可选 PostgreSQL 12+ 或 DB-less 声明式模式
  • 前置 Nginx 或云负载均衡已终结 TLS,Kong 只处理明文 8000
  • 上游服务地址与健康检查路径已确认,例如 http://10.0.0.21:8080/health
  • 注意:开源版 Admin API 没有任何内置认证,唯一可靠的保护是「只监听回环 + 前置代理鉴权 + 网络层白名单」,三者缺一不可

原理说明

Kong 的进程里同时跑着几张面孔:8000/8443 是数据面(代理流量),8001 是控制面(Admin API),8002 是 Kong Manager 图形界面,8003 是 Dev Portal。四个端口共用同一个进程,区分只靠监听地址。所以加固的第一步不是写插件,而是把 8001 从 0.0.0.0 改成 127.0.0.1——这一步能挡掉绝大多数自动化扫描器,因为公网上扫 8001 的僵尸网络比扫 22 端口的还勤。

插件模型是「绑定在服务或路由上的执行链」。同一类插件在服务级与路由级各配一份时,路由级优先;key-auth 负责认证、rate-limiting 负责配额、ip-restriction 负责来源、request-size-limiting 负责体积、response-transformer 负责补安全响应头。顺序上认证必须在限流之前,否则未认证请求会先消耗配额,形成「一个无效密钥打满全局限流」的拒绝服务面。

来源 IP 的正确性由三个配置决定:trusted_ips 声明哪些地址发来的 X-Forwarded-For 可信,real_ip_header 指定取哪个头,real_ip_recursive 决定是否从右往左剥掉可信跳数。三者不配,Kong 会把 TCP 连接的对端地址当客户端地址——在 Nginx 反代场景下,那个地址永远是 Nginx 自己,于是所有请求共享一个 IP,限流与白名单同时失效。

DB-less 模式下,所有配置来自一份 kong.yml,通过 kong reload 生效,不落库。它的好处是配置可进 Git、可审计、可回滚;代价是没有 Admin API 的写操作,改一条路由就要重新加载。对「变更走发布流程」的团队,这个约束反而是优点。

操作步骤

1. 端口收口

用环境变量方式部署,把 Admin API 与状态接口都压到回环,图形界面与门户直接关闭:

cat > /opt/kong/docker-compose.yml <<'EOF'
services:
  kong:
    image: kong:3.6
    container_name: kong
    restart: unless-stopped
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /kong/declarative/kong.yml
      KONG_PROXY_LISTEN: "0.0.0.0:8000"
      KONG_ADMIN_LISTEN: "127.0.0.1:8001"
      KONG_ADMIN_GUI_LISTEN: "off"
      KONG_PORTAL: "off"
      KONG_STATUS_LISTEN: "127.0.0.1:8100"
      KONG_TRUSTED_IPS: "10.0.0.0/8,127.0.0.1"
      KONG_REAL_IP_HEADER: "X-Forwarded-For"
      KONG_REAL_IP_RECURSIVE: "on"
      KONG_HEADERS: "off"
      KONG_LOG_LEVEL: "notice"
    volumes:
      - ./declarative:/kong/declarative
    ports:
      - "8000:8000"
EOF

sudo mkdir -p /opt/kong/declarative
cd /opt/kong && docker compose up -d

KONG_ADMIN_LISTEN 写成 127.0.0.1:8001 是本文最重要的一行,容器内回环意味着宿主机只能通过 docker exec 或 --network host 访问,公网彻底不可达。KONG_HEADERS: off 会关掉 Server: kong/x.y.z 的版本暴露,避免被按版本匹配 CVE,安全响应头统一由外层 Nginx 输出,避免两处重复添加。

2. 校正来源 IP 信任链

Nginx 反代 Kong 时,必须把真实客户端地址写进 X-Forwarded-For,并让 Kong 只信任 Nginx 所在网段:

server {
    listen 443 ssl;
    http2 on;
    server_name api.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Content-Type-Options "nosniff" always;

    client_max_body_size 4m;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 60s;
    }
}

proxy_add_x_forwarded_for 会把真实地址追加到已有的头后面,而不是覆盖。Kong 侧 real_ip_recursive: on 从右往左剥掉可信网段,最后剩下的第一个不可信地址才是客户端真实 IP。若写成 proxy_set_header X-Forwarded-For $remote_addr;(覆盖式),攻击者伪造的头会被丢弃,反而更安全;两种写法都能用,但只要有一层不校验就前功尽弃。

3. 声明式配置:鉴权、限流与来源限制

下面这份 kong.yml 定义了单个服务、一条路由、四个插件与一个消费者,可直接导入。密钥务必现场生成,不要用示例值:

_format_version: "3.0"

services:
  - name: order-api
    url: http://10.0.0.21:8080
    connect_timeout: 5000
    read_timeout: 10000
    routes:
      - name: order-api-route
        paths:
          - /api/order
        strip_path: true
        protocols:
          - http
          - https
    plugins:
      - name: key-auth
        config:
          key_names:
            - apikey
          hide_credentials: true
      - name: rate-limiting
        config:
          minute: 120
          hour: 3000
          policy: local
          limit_by: ip
          fault_tolerant: false
      - name: ip-restriction
        config:
          allow:
            - 10.0.0.0/8
            - 203.0.113.0/24
      - name: request-size-limiting
        config:
          allowed_payload_size: 2
          require_content_length: true
      - name: response-transformer
        config:
          add:
            headers:
              - "Referrer-Policy:strict-origin-when-cross-origin"
              - "X-Content-Type-Options:nosniff"

consumers:
  - username: partner-a
    keyauth_credentials:
      - key: 9f2c7a41d8e35b06c1a4f7d29b8e5301

几个参数值得单独说明:hide_credentials: true 会从转发给上游的请求里删掉 apikey,防止密钥在后端日志里落地;fault_tolerant: false 让限流在存储不可用时直接拒绝(默认是失败放行,等于攻击期间自动解除限流);allowed_payload_size 单位是 MB,配合 require_content_length 可拦住不带长度头的分块上传;strip_path: true 会把 /api/order 前缀剥掉再转给上游,与后端路由约定不一致时先改成 false 试。

4. 导入并校验

# 语法解析,不加载,先确认 YAML 与 schema 无误
docker exec kong kong config parse /kong/declarative/kong.yml

# DB-less 模式:重载声明式配置
docker exec kong kong reload

# 确认服务与路由已加载
curl -s http://127.0.0.1:8001/services | head -c 300
curl -s http://127.0.0.1:8001/routes  | head -c 300

kong config parse 失败会直接指出字段名与行号,比 import 后才报错好排查。DB 模式(有 PostgreSQL)则改用 kong config db_import /kong/declarative/kong.yml,导入是幂等的,同名服务会被更新而不是重复创建。

5. 密钥轮换与最小权限

消费者密钥一旦泄露,必须在声明式文件里换掉并重载。批量生成与核对:

# 生成 32 位十六进制密钥
openssl rand -hex 16

# 查看全部消费者的密钥(仅允许在本机执行)
curl -s http://127.0.0.1:8001/key-auths | grep -o '"key":"[^"]*"'

# 为已有消费者追加一个密钥,便于平滑切换
curl -s -X POST http://127.0.0.1:8001/consumers/partner-a/key-auth \
  -d '{"key":"<新密钥>","ttl":2592000}'

ttl 以秒计,2592000 即 30 天,到期自动失效,避免「一次发放永久有效」。轮换流程建议「先发新密钥 → 通知对方切换 → 观察两周调用量 → 删除旧密钥」,直接删旧密钥会造成硬中断。

配置验证

# 1) Admin API 仅本机可达
ss -tlnp | grep -E '8001|8100'
curl -s -o /dev/null -w 'local admin: %{http_code}\n' http://127.0.0.1:8001/

# 2) 公网访问业务接口,无密钥应 401
curl -s -o /dev/null -w '%{http_code}\n' https://api.example.com/api/order/list

# 3) 带密钥应 200
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'apikey: 9f2c7a41d8e35b06c1a4f7d29b8e5301' \
  https://api.example.com/api/order/list

# 4) 超频应 429
for i in $(seq 1 150); do
  curl -s -o /dev/null -w '%{http_code} ' \
    -H 'apikey: 9f2c7a41d8e35b06c1a4f7d29b8e5301' \
    https://api.example.com/api/order/list
done; echo

# 5) 伪造来源头不应绕过白名单
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'X-Forwarded-For: 10.0.0.9' \
  -H 'apikey: 9f2c7a41d8e35b06c1a4f7d29b8e5301' \
  https://api.example.com/api/order/list

# 6) 健康与版本
curl -s http://127.0.0.1:8100/status | head -c 200

预期:8001 只绑定 127.0.0.1;无密钥 401;带密钥 200;第 4 步在第 120 次之后开始出现 429;第 5 步应从公网来源拿到 403(被 ip-restriction 拒绝)而不是 200——如果拿到 200,说明 trusted_ips 把公网段也当成可信,伪造头生效了。

常见问题

FAQ 1:配了 ip-restriction 白名单,攻击者照样能进来?

先看 KONG_TRUSTED_IPS 是否过大。Kong 只信任来自 trusted_ips 网段的 X-Forwarded-For,若填成 0.0.0.0/0,任何人都能自带一个内网地址通过校验。正确做法是只填前置代理的地址段,并确保 real_ip_recursive 为 on。排查方法是在上游打印收到的 X-Real-IP,与实际出口 IP 对比。

FAQ 2:限流阈值明明是 120 次/分钟,却经常提前触发或根本不触发?

两种原因。一是 policy: local:计数存在各节点内存里,多副本部署时每个实例单独计数,实际阈值等于「120 × 副本数」;需要全局精确计数就换 redis 策略并指定 redis.host。二是 limit_by 选了 credential 或 consumer,此时同一 IP 上多个密钥互不影响,与你预期的「按 IP 限」不一致。fault_tolerant 为 true 时 Redis 抖动会让限流整体失效,安全场景应设为 false。

FAQ 3:DB-less 模式改了 kong.yml,为什么接口行为没变?

声明式配置不会自动热加载,必须执行 kong reload(容器内)。kong reload 只重读配置不重启进程,连接不会中断;但如果文件有语法错误,reload 会失败并保留旧配置,此时 docker logs kong 里能看到解析错误。生产环境建议先 kong config parse 再 reload,把错误挡在生效之前。

总结

Kong 的风险不在插件能力,而在「默认太开放」。加固的四步是递进的:KONG_ADMIN_LISTEN 收回到 127.0.0.1 解决控制面裸奔,trusted_ips 与 real_ip_recursive 校正来源 IP 解决白名单与限流被伪造头绕过,key-auth + rate-limiting + ip-restriction 三层插件解决调用侧准入,最后用 kong.yml 进版本库让每次变更可审计、可回滚。做完这四步,网关才真正成为「统一入口」而不是「统一后门」。