Apache APISIX 密钥认证(Key Authentication)完全指南

原创于 2025-06-02 09:16:55 发布 · 237 阅读

CC 4.0 BY-SA版权

Apache APISIX 密钥认证(Key Authentication)完全指南

apisix Apisix是一个基于Nginx的API网关，主要用于微服务架构中的API管理和服务发现。它的特点是高性能、轻量级、易于配置等。适用于API管理和负载均衡场景。项目地址: https://gitcode.com/gh_mirrors/api/apisix

什么是密钥认证

密钥认证(Key Authentication)是API网关中最基础也最常用的身份验证方式之一。它的核心原理是：

服务端为每个合法客户端分配一个唯一的API密钥
客户端在请求时必须携带这个密钥（通常放在请求头中）
服务端验证密钥的有效性，决定是否允许访问

在Apache APISIX中，密钥认证通过key-auth插件实现，具有配置简单、性能高效的特点。

为什么需要密钥认证

在微服务架构中，API网关作为系统的入口，需要确保：

只有经过授权的客户端才能访问后端服务
能够识别和追踪每个请求的来源
防止未授权的访问和恶意攻击

密钥认证提供了第一道安全防线，是API安全的基础保障。

在APISIX中配置密钥认证

准备工作

确保已安装并运行Apache APISIX
已创建至少一个路由（如未创建可参考路由配置教程）

创建消费者(Consumer)

消费者代表使用API的客户端应用或开发者。创建消费者时需要：

指定唯一用户名
配置认证插件及参数

curl -i "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT -d '
{
  "username": "client-app",
  "plugins": {
    "key-auth": {
      "key": "this-is-a-secret-key-123"
    }
  }
}'

安全建议：

密钥应足够复杂（建议16位以上，包含大小写字母、数字和特殊字符）
定期轮换密钥
不同客户端使用不同密钥

为路由启用密钥认证

curl -i "http://127.0.0.1:9180/apisix/admin/routes/example-route" -X PATCH -d '
{
  "plugins": {
    "key-auth": {}
  }
}'

启用后，该路由下的所有请求都必须携带有效密钥。

密钥传递方式

客户端可以通过以下两种方式传递密钥：

请求头方式（推荐）：

GET /api/resource HTTP/1.1
Host: example.com
apikey: this-is-a-secret-key-123

查询参数方式：

GET /api/resource?apikey=this-is-a-secret-key-123 HTTP/1.1
Host: example.com

验证密钥认证

测试未授权访问

curl -i "http://127.0.0.1:9080/api/resource"

应返回401 Unauthorized错误。

测试错误密钥

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

同样应返回401错误。

测试正确密钥

curl -i "http://127.0.0.1:9080/api/resource" -H 'apikey: this-is-a-secret-key-123'

应返回200 OK及正常响应内容。

高级配置

自定义密钥头字段

默认使用apikey头，可自定义为其他字段：

{
  "plugins": {
    "key-auth": {
      "header": "X-API-KEY"
    }
  }
}

禁用密钥认证

临时禁用而不删除配置：

curl "http://127.0.0.1:9180/apisix/admin/routes/example-route" -X PATCH -d '
{
  "plugins": {
    "key-auth": {
      "_meta": {
        "disable": true
      }
    }
  }
}'