跳到主要内容

key-auth

key-auth 插件支持使用身份认证密钥作为客户端在访问上游资源之前进行自我身份认证的机制。

要使用该插件，你需要在消费者（Consumer）上配置身份认证密钥，并在路由或服务上启用该插件。密钥可以包含在请求 URL 查询字符串或请求头中。APISIX 将验证密钥，以确定是否允许请求访问上游资源。

消费者成功通过身份认证后，APISIX 会在将请求代理到上游服务之前添加额外的请求头，例如 X-Consumer-Username、X-Credential-Identifier；如果配置了消费者自定义请求头，也会一并添加。上游服务可以据此区分消费者并执行额外逻辑。如果这些值不可用，则不会添加相应的请求头。

关于 X-Consumer-Username

使用 Ingress Controller 配置消费者时，消费者名称会生成为 namespace_consumername 格式。因此，X-Consumer-Username 请求头也会采用此格式，而不只是 consumername。

示例​

以下示例展示了如何在不同场景下使用 key-auth 插件。

在路由上实现密钥认证​

以下示例展示了如何在路由上实现密钥认证，并在请求头中携带密钥。

创建一个消费者 jack：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jack"
  }'

为该消费者创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-jack-key-auth",
    "plugins": {
      "key-auth": {
        "key": "jack-key"
      }
    }
  }'

创建一个启用 key-auth 的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "key-auth-route",
    "uri": "/anything",
    "plugins": {
      "key-auth": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

使用有效密钥进行验证​

使用有效密钥发送请求：

curl -i "http://127.0.0.1:9080/anything" -H 'apikey: jack-key'

你应该会收到 HTTP/1.1 200 OK 响应。

使用无效密钥进行验证​

使用无效密钥发送请求：

curl -i "http://127.0.0.1:9080/anything" -H 'apikey: wrong-key'

你应该会看到包含以下内容的 HTTP/1.1 401 Unauthorized 响应：

{"message":"Invalid API key in request"}

未提供密钥进行验证​

未提供密钥发送请求：

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

你应该会看到包含以下内容的 HTTP/1.1 401 Unauthorized 响应：

{"message":"Missing API key found in request"}

向上游隐藏认证信息​

以下示例展示了如何通过配置 hide_credentials 来防止密钥被发送到上游服务。默认情况下，认证密钥会被转发到上游服务，这在某些情况下可能会导致安全风险。

创建一个消费者 jack：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jack"
  }'

为该消费者创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-jack-key-auth",
    "plugins": {
      "key-auth": {
        "key": "jack-key"
      }
    }
  }'

不隐藏凭证​

创建一个启用 key-auth 的路由，并将 hide_credentials 配置为 false（这是默认配置）：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "id": "key-auth-route",
  "uri": "/anything",
  "plugins": {
    "key-auth": {
      "hide_credentials": false
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

使用有效密钥发送请求：

curl -i "http://127.0.0.1:9080/anything?apikey=jack-key"

你应该会看到包含以下内容的 HTTP/1.1 200 OK 响应：

{
  "args": {
    "apikey": "jack-key"
  },
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.2.1",
    "X-Consumer-Username": "jack",
    "X-Credential-Identifier": "cred-jack-key-auth",
    "X-Amzn-Trace-Id": "Root=1-6502d8a5-2194962a67aa21dd33f94bb2",
    "X-Forwarded-Host": "127.0.0.1"
  },
  "json": null,
  "method": "GET",
  "origin": "127.0.0.1, 103.248.35.179",
  "url": "http://127.0.0.1/anything?apikey=jack-key"
}

注意，凭证 jack-key 对上游服务可见。

隐藏凭证​

将插件的 hide_credentials 更新为 true：

curl "http://127.0.0.1:9180/apisix/admin/routes/key-auth-route" -X PATCH \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "plugins": {
    "key-auth": {
      "hide_credentials": true
    }
  }
}'

使用有效密钥发送请求：

curl -i "http://127.0.0.1:9080/anything?apikey=jack-key"

你应该会看到包含以下内容的 HTTP/1.1 200 OK 响应：

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.2.1",
    "X-Consumer-Username": "jack",
    "X-Credential-Identifier": "cred-jack-key-auth",
    "X-Amzn-Trace-Id": "Root=1-6502d85c-16f34dbb5629a5960183e803",
    "X-Forwarded-Host": "127.0.0.1"
  },
  "json": null,
  "method": "GET",
  "origin": "127.0.0.1, 103.248.35.179",
  "url": "http://127.0.0.1/anything"
}

注意，凭证 jack-key 不再对上游服务可见。

演示请求头和查询参数中密钥的优先级​

以下示例展示了如何在路由上按消费者实现密钥认证，并自定义用于携带密钥的 URL 参数。该示例还表明，当 API 密钥同时出现在请求头和查询字符串中时，请求头具有更高的优先级。

创建一个消费者 jack：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jack"
  }'

为该消费者创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-jack-key-auth",
    "plugins": {
      "key-auth": {
        "key": "jack-key"
      }
    }
  }'

创建一个启用 key-auth 的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
  "id": "key-auth-route",
  "uri": "/anything",
  "plugins": {
    "key-auth": {
      "query": "auth"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

使用有效密钥进行验证​

使用有效密钥发送请求：

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

你应该会收到 HTTP/1.1 200 OK 响应。

使用无效密钥进行验证​

使用无效密钥发送请求：

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

你应该会看到包含以下内容的 HTTP/1.1 401 Unauthorized 响应：

{"message":"Invalid API key in request"}

在 Query String 中使用有效密钥​

然而，如果你在请求头中携带有效密钥，而在 URL 查询字符串中仍使用无效密钥：

curl -i "http://127.0.0.1:9080/anything?auth=wrong-key" -H 'apikey: jack-key'

你应该会看到 HTTP/1.1 200 OK 响应。这表明请求头中的密钥始终具有更高的优先级。

将消费者自定义 ID 添加到请求头​

以下示例展示了如何将消费者自定义 ID 添加到已认证请求的 Consumer-Custom-Id 请求头中，以便按需实现额外逻辑。

创建一个带有自定义 ID 标签的消费者 jack：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jack",
    "labels": {
      "custom_id": "495aec6a"
    }
  }'

为该消费者创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-jack-key-auth",
    "plugins": {
      "key-auth": {
        "key": "jack-key"
      }
    }
  }'

创建一个启用 key-auth 的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "key-auth-route",
    "uri": "/anything",
    "plugins": {
      "key-auth": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

要进行验证，请使用有效密钥向路由发送请求：

curl -i "http://127.0.0.1:9080/anything?apikey=jack-key"

你应该会看到类似以下的 HTTP/1.1 200 OK 响应：

{
  "args": {
    "apikey": "jack-key"
  },
  "data": "", 
  "files": {}, 
  "form": {}, 
  "headers": {
    "Accept": "*/*", 
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0",
    "X-Amzn-Trace-Id": "Root=1-66ea8d64-33df89052ae198a706e18c2a", 
    "X-Consumer-Username": "aic_jack",
    "X-Consumer-Custom-Id": "495aec6a",
    "X-Forwarded-Host": "127.0.0.1"
  }, 
  "json": null, 
  "method": "GET", 
  "origin": "192.168.65.1, 205.198.122.37", 
  "url": "http://127.0.0.1/anything?apikey=jack-key"
}

如果你想将更多消费者自定义请求头添加到已认证请求中，请参阅 attach-consumer-label 插件。

针对匿名消费者的速率限制​

以下示例展示了如何针对普通消费者和匿名消费者配置不同的速率限制策略，其中匿名消费者无需认证，但配额较少。

创建一个普通消费者 jack，并配置 limit-count 插件，允许在 30 秒窗口内有 3 次配额：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "jack",
    "plugins": {
      "limit-count": {
        "count": 3,
        "time_window": 30,
        "rejected_code": 429,
        "policy": "local"
      }
    }
  }'

为消费者 jack 创建 key-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-jack-key-auth",
    "plugins": {
      "key-auth": {
        "key": "jack-key"
      }
    }
  }'

创建一个匿名用户 anonymous，并配置 limit-count 插件，允许在 30 秒窗口内有 1 次配额：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "anonymous",
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429,
        "policy": "local"
      }
    }
  }'

创建一个路由并配置 key-auth 插件，允许匿名消费者 anonymous 绕过认证：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "key-auth-route",
    "uri": "/anything",
    "plugins": {
      "key-auth": {
        "anonymous_consumer": "anonymous"
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

要进行验证，请使用 jack 的密钥连续发送 5 个请求：

resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H 'apikey: jack-key' -o /dev/null -s -w "%{http_code}\n") && \
  count_200=$(echo "$resp" | grep "200" | wc -l) && \
  count_429=$(echo "$resp" | grep "429" | wc -l) && \
  echo "200": $count_200, "429": $count_429

你应该会看到以下响应，显示在 5 个请求中，有 3 个请求成功（状态码 200），而其他请求被拒绝（状态码 429）。

200:    3, 429:    2

发送 5 个匿名请求：

resp=$(seq 5 | xargs -I{} curl "http://127.0.0.1:9080/anything" -o /dev/null -s -w "%{http_code}\n") && \
  count_200=$(echo "$resp" | grep "200" | wc -l) && \
  count_429=$(echo "$resp" | grep "429" | wc -l) && \
  echo "200": $count_200, "429": $count_429

你应该会看到以下响应，显示只有一个请求成功：

200:    1, 429:    4