a6-plugin-key-auth

概览

key-auth 插件使用 API Key 对请求进行认证。客户端会在 请求头、查询参数或 Cookie 中携带 key。Apache APISIX会根据该 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，存储到 etcd 时自动加密。

Key 查找优先级

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

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

1. 创建消费者

a6 consumer create -f - <<'EOF'
{
  "username": "alice"
}
EOF

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

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

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

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

a6 route create -f - <<'EOF'
{
  "id": "protected-api",
  "uri": "/api/*",
  "plugins": {
    "key-auth": {}
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "backend:8080": 1
    }
  }
}
EOF

4. 验证认证

# Should succeed (200)
curl -i http://127.0.0.1:9080/api/users -H "apikey: alice-secret-key-001"

# Should fail (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 请求头或查询参数会在到达后端前被移除。 生产环境中请始终启用该配置。

匿名消费者与限流

# Create anonymous consumer with strict limits
a6 consumer create -f - <<'EOF'
{
  "username": "anonymous",
  "plugins": {
    "limit-count": {
      "count": 10,
      "time_window": 60,
      "rejected_code": 429
    }
  }
}
EOF

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

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

添加到上游的请求头

认证成功后，Apache APISIX会添加：

请求头	值
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"
consumers:
  - username: alice
routes:
  - id: protected-api
    uri: /api/*
    plugins:
      key-auth: {}
    upstream_id: my-upstream
upstreams:
  - id: my-upstream
    type: roundrobin
    nodes:
      "backend:8080": 1

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

---

本文根据 api7/a6 仓库中的 a6-plugin-key-auth/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。