跳到主要内容
版本：3.10.x

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

概览​

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

适用场景​

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

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

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

消费者凭证参考​

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

Key 查找优先级​

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

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

将 <gateway-group-id> 替换为 a7 gateway-group list -o json 返回的 ID。

1. 创建消费者​

a7 consumer create -g <gateway-group-id> -f - <<'EOF'
{
  "username": "alice"
}
EOF

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

a7 credential create cred-alice-key-auth -g <gateway-group-id> \
  --consumer alice \
  --plugins-json '{"key-auth":{"key":"alice-secret-key-001"}}'

3. 创建启用 key-auth 的服务和路由​

a7 service create -g <gateway-group-id> -f - <<'EOF'
{
  "id": "protected-api-service",
  "name": "Protected API",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create -g <gateway-group-id> -f - <<'EOF'
{
  "id": "protected-api",
  "paths": ["/api/*"],
  "service_id": "protected-api-service",
  "plugins": {
    "key-auth": {}
  }
}
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 <gateway-group-id> -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 值
上游日志中可见 keyhide_credentials 为 false设置 hide_credentials: true
匿名用户未生效未设置 anonymous_consumer 或消费者不存在创建消费者并设置该字段

配置同步示例​

将以下内容保存为 key-auth.yaml：

version: "1"
services:
  - id: protected-api-service
    name: Protected API service
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1
routes:
  - id: protected-api
    name: Protected API route
    paths:
      - /api/*
    service_id: protected-api-service
    plugins:
      key-auth: {}

校验该部分配置，并将其应用到目标网关组：

a7 config validate -f key-auth.yaml
a7 config sync -g <gateway-group-id> -f key-auth.yaml --delete=false

注意：请分别使用 a7 consumer create 和 a7 credential create 创建消费者与凭证。本示例中的配置同步仅管理服务和路由。禁用删除可保留未包含在该部分配置中的其他资源。

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