Higress key-auth 插件基于 API Key 的认证鉴权配置全解析【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressHigress 的key-auth插件是一个运行在认证阶段AUTHN的 WASM 插件用于从请求的 URL 参数或 HTTP 请求头中提取 API Key将其与预配置的调用方consumer凭证做匹配完成认证 鉴权两层控制。读完本文你将掌握global_auth、consumers、keys、in_query/in_header、allow全部配置字段的用法与相互约束能复制仓库中真实的 WasmPlugin 部署清单完成接入并理解认证决策的完整代码路径与每一种失败响应的来源。1. 插件定位与运行属性从插件注册代码 main.go 可以看到key-auth通过wrapper.SetCtx向 Higress 的 wasm-go 框架注册了三个要素插件名key-auth配置解析器parseGlobalConfig实例/全局级与parseOverrideRuleConfig路由/域级组成的双段式解析请求处理入口ProcessRequestHeadersBy(onHttpRequestHeaders)即认证逻辑只作用于HTTP 请求头阶段请求体不参与认证认证失败时由网关直接本地回包请求不会转发到上游。源码注释声明的元信息main.go属性值说明执行阶段PhaseAUTHN认证阶段执行优先级Priority321当前仓库源码中的注解值README 文档中记载为310以源码注解为准失败响应头WWW-Authenticate: Key realmMSE Gateway由 main.go 的WWWAuthenticateHeader构造protectionSpace变量定义为MSE Gateway版本方面插件目录下的 VERSION 文件记录当前版本为1.0.0与源码Version 1.0.0注解一致。2. 配置字段说明注意继承自 README在一个规则里鉴权配置allow和认证配置consumers/keys等不可同时存在于同一层级认证配置属于实例global层allow属于路由/域名等细粒度规则层对通过认证鉴权的请求网关会向请求添加X-Mse-Consumer请求头其值为调用方名称供下游服务识别调用者身份。2.1 认证配置实例级名称数据类型填写要求默认值描述global_authbool选填仅实例级别配置-配置为true时全局生效认证机制配置为false时只对做了配置的域名和路由生效不配置时仅当没有任何域名/路由级配置时全局生效兼容老用户使用习惯consumersarray of object必填-配置服务的调用者用于对请求进行认证keysarray of string必填-API Key 的来源字段名称列表可以是 URL 参数名或 HTTP 请求头名可配置多个in_querybool与in_header至少显式配置一个-为true时网关尝试从 URL 参数中解析 API Keyin_headerbool与in_query至少显式配置一个-为true时网关尝试从 HTTP 请求头中解析 API Keyconsumers中每一项对应源码结构体 Consumer名称数据类型填写要求描述credentialstring与credentials二选一该 consumer 的一个访问凭证credentialsarray of string与credential二选一该 consumer 的多个访问凭证如凭证轮转场景不能与credential同时配置namestring必填该 consumer 的名称认证通过后写入X-Mse-Consumer结合源码 parseGlobalConfig 可以补充文档未列出的加载期校验规则——以下任一情况会导致插件启动失败OnPluginStartStatusFailed配置不生效缺少keys或keys为空数组L155-L161in_query与in_header均未显式配置L167-L172——因此这两个字段需要显式写出而不是依赖默认值缺少consumers或为空数组L182-L188consumer 缺少name或name为空串credential/credentials二选一同时出现或都为空、credentials数组为空、数组内存在空字符串凭证均会报错L190-L220任一凭证重复含跨 consumer 的credential与credentials交叉重复duplicate consumer credentialL222-L226。解析完成后插件会构建一张credential → consumer 名称的哈希表credential2NameL238-L240认证时直接查表完成凭证到调用方的映射。2.2 鉴权配置路由/域级非必需名称数据类型填写要求描述allowarray of string选填非实例级别配置只能在路由或域名等细粒度规则上配置列出允许访问该规则的 consumer 名称实现细粒度权限控制allow的解析逻辑见 parseOverrideRuleConfig规则级配置中allow为必填且不能为空数组缺失L251-L253或为空L254-L256都会使配置加载失败。同时该函数将全局配置复制进当前规则的配置副本*config global并把全局标记ruleSet置为trueL261供运行时判断是否存在任意一个生效的路由/域规则。3. 认证决策流程onHttpRequestHeaders 源码解析核心处理函数 onHttpRequestHeaders 的注释L266-L277完整描述了决策矩阵整理如下场景global_auth当前路由/域是否配置了allow行为①true否在全部 consumers 中查找凭证找到即认证通过②true是凭证须同时存在于allow列表否则 403③false否直接放行不做认证④false是凭证须存在于allow列表否则 403⑤未设置没有任何规则配置过该插件等同于 ①全局生效兼容老用户⑥未设置至少一个规则配置过该插件等同于 ③/④只对配置过的规则生效逐步骤拆解免认证短路L285-L293当global_authfalse或global_auth未设置且存在任意规则配置ruleSettrue时若当前路由/域没有allow列表即插件未在该规则生效记录authorization is not required日志并ActionContinue放行。提取 API KeyL298-L317in_headertrue时遍历keys中的每个名称调用proxywasm.GetHttpRequestHeader收集值in_querytrue时从:path头解析 URL 的 query 参数收集keys命中的参数值从源码的if InHeader { … } else if InQuery { … }结构看两者同时为true时优先走请求头路径不会合并两个来源的结果。数量校验L319-L324提取到多个 Keylen(tokens) 1→ 401一个都没有 → 401。凭证匹配L326-L333查credential2Name表查不到即拒绝查到时立即AddHttpRequestHeader(X-Mse-Consumer, name)。allow 判定L335-L363按上表 ①④ 分派不在allow内的已认证 consumer 同样返回 403deniedUnauthorizedConsumer。4. 配置示例全局配置认证 路由/域粒度鉴权以下示例继承自 READMEcredential或credentials中的访问凭证不能重复。实例级插件配置global_auth: false consumers: - credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5 name: consumer1 - credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35 name: consumer2 keys: - apikey - x-api-key对 route-a、route-b 两个路由配置allow: - consumer1对 *.example.com、test.com 两个域名配置allow: - consumer2说明此例中 route-a、route-b 是创建网关路由时填写的路由名称请求匹配到这两个路由时只允许name为consumer1的调用者访问当请求域名匹配*.example.com或test.com时只允许consumer2访问。按该配置下列请求被允许假设请求匹配到 route-aAPI Key 放在 URL 参数中curl http://xxx.hello.com/test?apikey2bda943c-ba2b-11ec-ba07-00163e1250b5API Key 放在请求头中curl http://xxx.hello.com/test -H x-api-key: 2bda943c-ba2b-11ec-ba07-00163e1250b5认证鉴权通过后请求头中会被添加X-Mse-Consumer字段此例中其值为consumer1标识调用方名称。下列请求将被拒绝未提供 API Keycurl http://xxx.hello.com/test提供的 API Key 无权访问不在 consumers 配置内curl http://xxx.hello.com/test?apikey926d90ac-ba2e-11ec-ab68-00163e1250b5API Key 能匹配到调用者但该调用者无此路由权限consumer2 不在 route-a 的 allow 列表中curl http://xxx.hello.com/test?apikeyc8c8e9ca-558e-4a2d-bb62-e700dcc40e355. 网关实例级别开启全局认证global_auth: true consumers: - credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5 name: consumer1 - credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35 name: consumer2 keys: - apikey - x-api-key此时所有请求都必须携带有效 API Key 才能访问未配置allow的路由只需通过 consumers 凭证认证见第 3 节场景 ①。6. Kubernetes 下的真实部署清单仓库中提供了一份可直接参考的 K8s 部署清单 keyauth.yaml展示了 key-auth 与 Higress Ingress/McpBridge 资源配合的完整形态apiVersion: networking.higress.io/v1 kind: McpBridge metadata: name: mcp-keyauth-httpbin namespace: higress-system spec: registries: - domain: httpbin.org name: httpbin port: 80 type: dns --- apiVersion: networking.k8s.io/v1 kind: Ingress metadata: annotations: higress.io/destination: httpbin.dns higress.io/upstream-vhost: httpbin.org higress.io/backend-protocol: HTTP name: ingress-keyauth-httpbin namespace: higress-system spec: ingressClassName: higress rules: - host: httpbin.example.com http: paths: - backend: resource: apiGroup: networking.higress.io kind: McpBridge name: mcp-keyauth-httpbin path: / pathType: Prefix --- apiVersion: extensions.higress.io/v1alpha1 kind: WasmPlugin metadata: name: wasm-keyauth-httpbin namespace: higress-system spec: defaultConfig: consumers: - credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5 name: consumer1 - credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35 name: consumer2 global_auth: false keys: - x-api-key - apikey in_header: true defaultConfigDisable: false matchRules: - config: allow: - consumer1 configDisable: false ingress: - ingress-keyauth-httpbin url: oci://docker.io/dongjiang1989/keyauth:1.0.0 imagePullPolicy: Always对照第 2 节的字段模型这份清单恰好演示了标准的分层方式defaultConfig承载实例级认证配置consumers、keys、in_header、global_auth: falsematchRules中针对指定 Ingressingress-keyauth-httpbin的规则只放allow: [consumer1]做鉴权——即只有consumer1能访问该 Ingress 对应路由consumer2即使凭证有效也会被 403 拒绝。spec.url指向插件的 OCI 镜像地址这是 Higress 通过 WasmPlugin CR 下发 WASM 插件的标准方式。7. 错误码与拒绝响应三个拒绝函数 deniedMultiKeyAuthData / deniedNoKeyAuthData / deniedUnauthorizedConsumer 都调用SendHttpResponseWithDetail本地回包并统一附加WWW-Authenticate: Key realmMSE Gateway响应头。基于当前源码与测试实际响应为HTTP 状态码响应体detail触发条件401key-auth.multi_key— Request denied by Key Auth check. Multi Key Authentication information found.请求同时在多个keys来源中提供了 API Key401key-auth.no_key— Request denied by Key Auth check. No Key Authentication information found.请求未提供任何 API Key403key-auth.unauthorized— Request denied by Key Auth check. Unauthorized consumer.API Key 不在 consumers 配置内或已认证但调用方不在该路由/域的allow列表中需要说明的是README 的错误码表将Invalid API key不允许当前 API Key 访问记为 401但从当前源码看未知凭证与调用方无权限走的是同一个 403 分支测试用例 main_test.goglobal auth true - invalid api key断言403 Forbidden与 main_extra_test.goallow 列表外 consumer 断言 403均印证了这一点排障时请以实际响应体中的 detail 字符串为准。8. 测试覆盖与源码索引该插件带有相当完整的测试可直接在仓库中查证各行为分支关注点测试文件全局/规则配置解析、非法配置缺 keys、缺 consumers、缺 in_query/in_header、凭证重复、credential 与 credentials 混用等main_test.go认证通过注入X-Mse-Consumer、多 Key 拒绝 401、缺 Key 拒绝 401、query 取 Key 等main_test.goglobal_auth三种取值 × allow 列表内外、allow缺失等边界分支main_extra_test.go关键源码与资源索引插件主实现配置解析 认证逻辑main.go部署示例清单keyauth.yaml配置参考文档README.md / README_EN.md模块依赖go 1.24、proxy-wasm-go-sdk、wasm-go、gjsongo.mod9. 实践要点小结分层配置是硬性约束consumers/keys/in_query/in_header/global_auth只能放实例级allow只能放路由/域级同一层级混放会触发加载失败。in_query与in_header必须显式给出至少一个两者同配时优先读请求头。凭证必须全局唯一且credential与credentials互斥credentials数组适合凭证轮转场景测试用例 pluralCredentialsConfig 验证了多凭证均能命中同一 consumer。安全上优先使用请求头传递 Keyin_header: true避免 Key 出现在 URL 中被日志、代理或浏览器历史记录留存。下游识别调用方统一读取X-Mse-Consumer头该头由网关在认证通过后注入main.go无需上游业务自行解析凭证。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考