API7 网关 AI Agent Skill：key-auth 插件

概览

key-auth 插件使用 API Key（API 密钥）对请求进行身份认证。客户端会在请求头、查询参数或 Cookie 中携带 API Key。API7 企业版会根据该 API Key 查找消费者凭证；匹配成功后，会携带消费者身份请求头转发请求。身份认证失败时返回 401 Unauthorized。

适用场景

• 使用简单的 API Key 身份认证保护路由
• 识别调用 API 的消费者
• 与限流结合，实现分层访问（已通过身份认证的用户与匿名用户）
• 对上游隐藏凭证。

插件配置参考（路由/服务）

字段	类型	是否必填	默认值	说明
header	string	否	"apikey"	提取 API Key 的请求头名称
query	string	否	"apikey"	查询参数名称（优先级低于请求头）
hide_credentials	boolean	否	false	转发到上游前从请求中移除 Key
anonymous_consumer	string	否	—	未通过身份认证的请求所使用的消费者用户名
realm	string	否	"key"	401 响应中 WWW-Authenticate 响应头的 realm

消费者凭证参考

字段	类型	是否必填	说明
key	string	是	消费者的唯一 API Key，会在数据库中自动加密。

Key 查找优先级

1. 请求头（默认：apikey）：优先检查
2. 查询参数（默认：apikey）：请求头不存在时检查
3. 如果两者都不存在，则返回 401 Unauthorized 和 "Missing API key in request"

分步操作：在路由上启用 key-auth

1. 创建消费者

a7 consumer create -g default -f - <<'EOF'
{
  "username": "alice"
}
EOF

2. 为消费者添加 key-auth 凭证

使用 Admin API（凭证是消费者的子资源）：

curl -k "https://$(a7 context current -o json | jq -r .server):7443/apisix/admin/consumers/alice/credentials" \
  -X PUT \
  -H "X-API-KEY: $(a7 context current -o json | jq -r .token)" \
  -d '{
    "id": "cred-alice-key-auth",
    "plugins": {
      "key-auth": {
        "key": "alice-secret-key-001"
      }
    }
  }'

3. 创建启用 key-auth 的路由

a7 route create -g default -f - <<'EOF'
{
  "id": "protected-api",
  "uri": "/api/*",
  "plugins": {
    "key-auth": {}
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

4. 验证身份认证是否成功

# 应该成功（200）
curl -i http://127.0.0.1:9080/api/users -H "apikey: alice-secret-key-001"

# 应该失败（401）
curl -i http://127.0.0.1:9080/api/users

常见模式

自定义请求头名称

{
  "plugins": {
    "key-auth": {
      "header": "X-API-Token"
    }
  }
}

客户端发送：curl -H "X-API-Token: alice-secret-key-001" ...

查询参数身份认证

{
  "plugins": {
    "key-auth": {
      "query": "token"
    }
  }
}

客户端发送：curl "http://127.0.0.1:9080/api/users?token=alice-secret-key-001"

对上游隐藏凭证

{
  "plugins": {
    "key-auth": {
      "hide_credentials": true
    }
  }
}

apikey 请求头或查询参数会在到达后端前被移除。生产环境中请始终启用该配置。

匿名消费者与限流

# 创建采用严格限流的匿名消费者
a7 consumer create -g default -f - <<'EOF'
{
  "username": "anonymous",
  "plugins": {
    "limit-count": {
      "count": 10,
      "time_window": 60,
      "rejected_code": 429
    }
  }
}
EOF

{
  "plugins": {
    "key-auth": {
      "anonymous_consumer": "anonymous"
    }
  }
}

带有效 key 的请求会映射到已通过身份认证的消费者；不带 key 的请求会映射到带有限流配置的匿名消费者。

添加到上游的请求头

身份认证成功后，API7 企业版会添加：

请求头	值
X-Consumer-Username	消费者用户名
X-Credential-Identifier	凭证 ID
X-Consumer-Custom-Id	消费者的 labels.custom_id（如已设置）

故障排查

现象	原因	修复方式
401 "Missing API key in request"	请求头或查询参数中没有 key	添加 apikey 请求头或查询参数
401 "Invalid API key in request"	Key 与任何消费者都不匹配	校验消费者凭证中的 key 值
上游日志中可见 key	hide_credentials 为 false	设置 hide_credentials: true
匿名用户未生效	未设置 anonymous_consumer 或消费者不存在	创建消费者并设置该字段

配置同步示例

version: "1"
gateway_groups:
  - name: default
    consumers:
      - username: alice
    routes:
      - id: protected-api
        uri: /api/*
        plugins:
          key-auth: {}
        upstream:
          type: roundrobin
          nodes:
            - host: backend
              port: 8080
              weight: 1

注意：消费者凭证必须通过 Admin API 单独创建；a7 config sync 会管理消费者资源，但凭证属于子资源。

---

本页面由 api7/a7 仓库中的 a7-plugin-key-auth/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。