Apache APISIX 插件 key-auth 自定义请求头配置详解

Apache APISIX 是一个高性能的云原生 API 网关，其中 key-auth 插件是常用的认证插件之一。该插件默认会从请求头中的 apikey 字段获取认证密钥，但在实际业务场景中，我们可能需要自定义这个请求头字段。

key-auth 插件基本工作原理

key-auth 插件基于 API 密钥进行身份验证，其工作流程如下：

1. 管理员在 APISIX 中为路由或服务配置 key-auth 插件
2. 插件会为每个消费者(Consumer)分配唯一的 API 密钥
3. 客户端请求时需要在请求头中携带这个密钥
4. APISIX 网关会验证密钥的有效性，通过后才能访问后端服务

自定义请求头配置方法

默认情况下，插件会从 apikey 请求头中获取密钥。要修改这个默认行为，可以在插件配置中指定 header 参数：

{
    "key-auth": {
        "header": "Authorization"
    }
}

配置后，插件将从 Authorization 请求头中获取 API 密钥，而不是默认的 apikey 头。

实际应用场景

自定义请求头在以下场景中特别有用：

1. 与现有系统集成：当客户端已经使用特定头字段(如 Authorization)传递认证信息时
2. 安全合规要求：某些安全规范可能要求使用特定的头字段名称
3. 多认证机制共存：系统中同时使用多种认证方式时，通过不同头字段区分

最佳实践建议

1. 选择符合行业标准的请求头名称，如 Authorization
2. 确保客户端和服务器配置一致，避免因头字段不匹配导致认证失败
3. 在生产环境变更前，先在测试环境验证自定义头的配置
4. 考虑在文档中明确说明所需的请求头字段，方便客户端开发者集成

通过灵活配置 key-auth 插件的请求头字段，可以更好地将 APISIX 集成到现有系统中，同时满足各种安全和业务需求。