跳到主要内容

key-auth

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

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

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

示例​

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

在路由上实现密钥认证​

以下示例展示了如何在路由上实现密钥认证，并将密钥包含在请求 Header 中。

创建一个消费者 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 不再对上游服务可见。

演示 Header 和 Query 中密钥的优先级​

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

创建一个消费者 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 中使用有效密钥​

然而，如果你在 Header 中包含有效密钥，而在 URL 查询字符串中仍然使用无效密钥：

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

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

将消费者自定义 ID 添加到 Header​

以下示例展示了如何将消费者自定义 ID 附加到认证请求的 Consumer-Custom-Id Header 中，这可用于实现所需的额外逻辑。

创建一个带有自定义 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": "jack",
    "X-Credential-Identifier": "cred-jack-key-auth",
    "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?auth=jack-key"
}

如果你想将更多的消费者自定义 Header 附加到认证请求中，请参阅 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
      }
    }
  }'

为消费者 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
      }
    }
  }'

创建一个路由并配置 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