配置 Key 身份认证

Key 身份认证是保护 API 最简单的方式之一。每个客户端都会获得唯一 API Key，并且必须在请求中提供它。API7 网关会先根据消费者凭证数据库验证该 Key，再允许请求继续发送到上游服务。

key-auth插件实现了此模式，并支持从请求头和查询参数中查找 Key。

本指南介绍标准配置流程。有关完整插件字段参考以及匿名消费者、凭证转发等高级行为，请参阅 key-auth。

前置条件

• API7 企业版实例正在运行。
• 已创建网关组且网关实例正在运行。
• 一个 Dashboard Token。

配置 Key 身份认证

配置 Key 身份认证包含三个步骤：

1. 创建具有有效上游的服务。
2. 创建启用 key-auth 的路由。
3. 创建消费者并挂载 Key 凭据。

第 1 步：创建具有上游的服务

创建一个将请求代理到 httpbin.org 的服务。

Admin API

curl -k "https://localhost:7443/apisix/admin/services/key-auth-httpbin-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "key-auth-httpbin-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

ADC

adc.yaml

services:
  - name: key-auth-httpbin-service
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: key-auth-route
        uris:
          - /anything/key-auth
        methods:
          - GET
        plugins:
          key-auth:
            header: apikey
consumers:
  - username: key-auth-consumer
    credentials:
      - name: key-auth-consumer-cred
        type: key-auth
        config:
          key: secret-api-key

adc sync -f adc.yaml

第 2 步：创建路由并启用 key-auth

创建指向该服务且要求使用 apikey 请求头的路由。

Admin API

curl -k "https://localhost:7443/apisix/admin/routes/key-auth-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "key-auth-route",
    "paths": ["/anything/key-auth"],
    "methods": ["GET"],
    "service_id": "key-auth-httpbin-service",
    "plugins": {
      "key-auth": {
        "header": "apikey"
      }
    }
  }'

ADC

该路由已包含在前面的 adc.yaml 示例中。

第 3 步：创建消费者和凭证

创建代表客户端的消费者，然后挂载 key-auth凭证。

Admin API

# 1. Create the consumer
curl -k "https://localhost:7443/apisix/admin/consumers/key-auth-consumer?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "key-auth-consumer"
  }'

# 2. Create the key-auth credential
curl -k "https://localhost:7443/apisix/admin/consumers/key-auth-consumer/credentials/key-auth-consumer-cred?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "key-auth-consumer-cred",
    "plugins": {
      "key-auth": {
        "key": "secret-api-key"
      }
    }
  }'

ADC

消费者和凭证已包含在前面的 adc.yaml 示例中。

验证配置

发送不含 API Key 的请求。网关应返回 401 Unauthorized 拒绝请求：

curl -i "http://127.0.0.1:9080/anything/key-auth"

然后使用正确的 API Key 发送请求：

curl -i "http://127.0.0.1:9080/anything/key-auth" \
  -H "apikey: secret-api-key"

应收到 200 OK，上游响应应包含类似以下的请求头：

{
  "headers": {
    "Apikey": "secret-api-key",
    "X-Consumer-Username": "key-auth-consumer",
    "X-Credential-Identifier": "key-auth-consumer-cred"
  }
}

如果应用配置后，已认证请求仍返回 401 或路由返回 404，请等待几秒，让最新配置下发到网关后重试。

后续步骤

• 配置 Basic 身份认证——使用标准用户名和密码凭证。
• 配置 JWT 身份认证——使用 JSON Web Token 实现无状态身份认证。
• 了解消费者和凭证——理解 API7 网关如何管理 API 身份。