Higress 网关 basic-auth 插件深度指南基于 HTTP Basic Auth 的认证鉴权配置与源码解析【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress导读basic-auth是 HigressAI Native API Gateway内置的 Wasm 插件基于 HTTP Basic Auth 标准为网关路由与域名提供认证Authentication与鉴权Authorization能力。本文以 plugins/wasm-cpp/extensions/basic_auth/README_EN.md 为主线完整讲解插件的运行属性、认证/鉴权配置字段、全局认证与路由/域名粒度授权的最佳实践、常见错误码并结合 plugin.cc、plugin.h、route_rule_matcher.h 与 plugin_test.cc 的源码与测试用例深入剖析请求校验链路、凭证编码规则与底层匹配机制帮助你在生产网关中快速落地 Basic Auth 鉴权并具备排障能力。功能说明与运行属性basic-auth插件实现基于 HTTP Basic Auth 标准的认证鉴权能力认证校验请求Authorization请求头中携带的用户名/密码以 Base64 编码确认调用者身份鉴权在认证通过后根据路由/域名粒度的allow列表判断该调用者是否有权访问目标资源。插件的运行属性如下见 README_EN.md属性值插件执行阶段认证阶段Authentication Phase插件执行优先级320在 Higress 中插件执行优先级数值越小越先执行优先级 320 位于认证阶段保证在路由转发、限流等后续逻辑之前完成身份识别。从源码看该插件挂载在请求头处理钩子上PluginContext::onRequestHeaders在 plugin.cc 中调用根上下文的checkAuthRule一旦校验失败即返回FilterHeadersStatus::StopIteration中断后续过滤器链校验通过则返回Continue放行。配置字段详解插件支持两种粒度的配置认证配置实例级定义调用者consumer及其访问凭证鉴权配置路由/域名级非必需通过allow列表决定哪些调用者可访问匹配的请求。注意来自官方文档在一个规则rule里鉴权配置与认证配置不可同时存在对于通过认证鉴权的请求请求 header 会被添加一个X-Mse-Consumer字段用以标识调用者名称便于下游服务识别真实调用方。认证配置名称数据类型填写要求默认值描述global_authbool选填仅实例级别配置-只能在实例级别配置true则全局生效认证机制false则只对做了配置的域名和路由生效认证机制不配置则仅在没有任何域名/路由配置时全局生效兼容老用户使用习惯。consumersarray of object必填-配置服务的调用者用于对请求进行认证。consumers中每一项的配置字段名称数据类型填写要求默认值描述credentialstring必填-配置该 consumer 的访问凭证格式为用户名:密码或 Base64 编码形式。namestring必填-配置该 consumer 的名称用于后续allow鉴权与X-Mse-Consumer透传。鉴权配置非必需名称数据类型填写要求默认值描述allowarray of string必填-对符合匹配条件的请求配置允许访问的 consumer 名称列表。源码级补充凭证的存储与校验形式从 plugin.h 的BasicAuthConfigRule结构体可以看出插件在内部维护了三类数据结构encoded_credentialsunordered_set明文凭证按 Base64 编码后存储用于快速比对请求携带的Authorization头encrypted_credentialsunordered_map加密凭证用户名 → 加密串映射用于encrypted: true场景credential_to_nameunordered_map凭证 → consumer 名称映射用于鉴权判定与X-Mse-Consumer注入。parsePluginConfigplugin.cc的解析逻辑揭示了凭证的三种合法形态包含:的字符串如admin:123456直接存储不包含:但能被 Base64 解码的字符串如YWRtaW46MTIzNDU2即admin:123456的编码同样接受当encrypted: true时凭证按用户名:加密串形式存储插件在请求到达时通过Wasm::Common::Crypto::crypt对用户输入密码进行加盐哈希比对见 plugin.cc。此外还有两个文档未展开但源码确认的配置项realm自定义 401/403 响应中WWW-Authenticate头的 realm 提示信息默认值为MSE Gatewayplugin.hencrypted布尔值开启密码加密存储模式plugin.cc。credential字段不能重复若两个 consumer 使用同一凭证配置解析会失败并输出duplicate consumer credential告警plugin.cc对应的单测OnConfigureDuplicateCredential位于 plugin_test.cc。同时插件对“多凭证映射到同一 consumer 名称”是允许的即一个 consumer 可以拥有多个用户名/密码。配置示例全局认证 路由/域名粒度鉴权以下配置将对网关特定路由或域名开启 Basic Auth 认证与鉴权。凭证信息中用户名和密码之间使用:分隔credential字段不能重复。第一步实例级别配置 consumersconsumers: - credential: admin:123456 name: consumer1 - credential: guest:abc name: consumer2 global_auth: falseglobal_auth: false表示认证机制只对配置了规则的路由/域名生效其余流量不受 Basic Auth 约束。第二步路由粒度鉴权对route-a和route-b两个路由配置allow: - consumer1第三步域名粒度鉴权对*.example.com和test.com两个域名配置allow: - consumer2配置效果说明若在 Higress 控制台配置route-a、route-b即创建路由时填写的路由名称。当请求匹配到这两个路由时仅name为consumer1的调用者允许访问其他调用者拒绝*.example.com与test.com用于匹配请求域名命中后仅name为consumer2的调用者允许访问。这一“实例级定义调用者 路由/域名级授权”的模型可以灵活实现一套凭证库、多套访问策略例如consumer1只开放给核心 API 路由consumer2仅开放给公开域名。允许访问的请求示例# 假设以下请求匹配到 route-a 路由 # 方式一使用 curl 的 -u 参数指定用户名密码 curl -u admin:123456 http://xxx.hello.com/test # 方式二直接指定 Authorization 请求头用户名密码使用 Base64 编码 # admin:123456 的 Base64 编码为 YWRtaW46MTIzNDU2 curl -H Authorization: Basic YWRtaW46MTIzNDU2 http://xxx.hello.com/test认证鉴权通过后请求 header 中会新增X-Mse-Consumer字段本例其值为consumer1下游服务可直接读取该头识别调用方。该行为由源码 plugin.cc 中的addRequestHeader(X-Mse-Consumer, credential_to_name_iter-second)实现。拒绝访问的请求示例# 1. 请求未提供用户名密码返回 401 curl http://xxx.hello.com/test # 2. 请求提供的用户名密码错误返回 401 curl -u admin:abc http://xxx.hello.com/test # 3. 根据用户名密码匹配到的调用者无访问权限返回 403 # consumer2 不在 route-a 的 allow 列表里 curl -u guest:abc http://xxx.hello.com/test请求校验的底层链路理解校验链路有助于配置排查。结合 plugin.cc 与 route_rule_matcher.h一次请求的完整判定流程如下规则匹配PluginContext::onRequestHeaders触发后根上下文调用checkAuthRuleroute_rule_matcher.h根据请求的:authority域名、route_name路由名、cluster_name服务名从_rules_中找到命中的规则及其allow集合头格式检查checkPlugin读取authorization请求头必须以Basic开头plugin.cc否则直接 401凭证比对将Basic后的凭证串与encoded_credentials集合比对明文模式或 Base64 解码后拆分用户名/密码并与encrypted_credentials哈希比对加密模式不匹配返回 401鉴权判定凭证命中后通过credential_to_name找到 consumer 名称若命中规则存在非空allow列表且该 consumer 不在其中返回 403plugin.cc透传标识通过鉴权后注入X-Mse-Consumer头请求继续流转。域名与路由的通配匹配规则route_rule_matcher.h的parseDomainMatchConfigroute_rule_matcher.h与hostMatchroute_rule_matcher.h定义了域名匹配语义*.example.com以*开头 →后缀匹配命中所有以.example.com结尾的域名匹配时会先剥离请求 Host 的端口test.com无通配符 →精确匹配以*结尾的域名 →前缀匹配。规则优先级遵循“先匹配先生效”原则且支持_match_route_、_match_route_prefix_路由前缀、_match_domain_、_match_service_服务四种匹配维度见 route_rule_matcher.h 的类别判定逻辑并可搭配_disable_字段关闭某条规则。global_auth 的行为语义源码确认parseAuthRuleConfigroute_rule_matcher.h解析global_auth并存入global_auth_。getMatchAuthConfigroute_rule_matcher.h的返回逻辑可以精确解释文档中的三种行为global_auth: true即使没有命中任何规则也使用全局配置强制认证未命中规则或凭证无效的请求一律 401对应单测GlobalAuthRuleWithDomainPort见 plugin_test.ccglobal_auth: false仅当请求命中某条规则时才执行认证未命中的请求直接放行对应单测OnConfigureNoRulesAuth的 disable 分支见 plugin_test.cc未配置当不存在任何_rules_时全局生效兼容老用户习惯存在_rules_时退化为“仅规则生效”。加密凭证模式encrypted对于凭证安全性要求较高的场景插件支持encrypted: true模式配置文件中存放的是密码哈希而非明文密码。从 plugin_test.cc 的GlobalAllow测试用例可以看到插件通过Wasm::Common::Crypto::crypt支持多种密码哈希算法算法凭证示例crypt 传统 DES 哈希myName:rqXexS6ZhobKAbcryptmyName:$2y$05$c4WoMPo3SXsafkva.HHa6uXQZWr7oboPiC2bT/r7q1BB8I2s0BRqCApache MD5 (apr1)myName:$apr1$EXfBN1bF$nuywSFTnPTcqbH5z4x6IG/明文myName:{PLAIN}myPasswordSHA1myName:{SHA}VBPuJHI7uixaa6LQGWx4s5GKNESSHAmyName:{SSHA}98JUfJee5Wb13m5683sLku40P3Y2VjNX加密模式下的配置示例对应单测RuleWithEncryptedConsumerAllow见 plugin_test.ccencrypted: true consumers: - credential: myName:$2y$05$c4WoMPo3SXsafkva.HHa6uXQZWr7oboPiC2bT/r7q1BB8I2s0BRqC name: consumer请求时仍使用明文密码如curl -u myName:myPassword ...插件在运行时对密码做哈希后与配置比对从而避免明文凭证直接落盘。注意encrypted: true模式下凭证必须包含:用户名与哈希串分隔否则配置解析会失败并告警colon not found in encrypted credentialplugin.cc。常见错误码与排障HTTP 状态码出错信息原因说明401Request denied by Basic Auth check. No Basic Authentication information found.请求未提供凭证缺少或格式错误的Authorization头。401Request denied by Basic Auth check. Invalid username and/or password.请求凭证无效用户名或密码错误。403Request denied by Basic Auth check. Unauthorized consumer.请求的调用方无访问权限凭证有效但不在命中规则的allow列表中。排障要点401 且提示 No Basic Authentication information found确认客户端确实携带了Authorization: Basic base64头且以Basic前缀开头——插件通过absl::StartsWith(authorization, Basic )严格校验前缀plugin.cc401 且提示 Invalid username and/or password核对consumers中的credential是否与请求用户名/密码一致注意凭证中:前是用户名、后是密码且 Base64 编码不得带填充符号插件使用Base64::decodeWithoutPadding403 Unauthorized consumer检查请求命中规则路由/域名的allow列表是否包含该凭证映射的 consumer 名称同时确认该规则是路由匹配还是域名匹配可结合规则内_match_route_/_match_domain_判定配置加载失败consumers与credentials不能在同一层级混用、同一凭证不能映射到两个 consumer、规则必须至少包含一种匹配维度路由/域名/服务/路由前缀这些约束均有对应单测覆盖见 plugin_test.cc 与 plugin_test.cc。源码结构与测试验证插件位于 plugins/wasm-cpp/extensions/basic_auth/核心文件包括plugin.cc配置解析parsePluginConfig、请求校验checkPlugin、三种拒绝响应的构造deniedNoBasicAuthData/deniedInvalidCredentials/deniedUnauthorizedConsumer见 plugin.cc均附带WWW-Authenticate: Basic realm...响应头以提示客户端弹窗plugin.hBasicAuthConfigRule数据结构与PluginRootContext/PluginContext类声明route_rule_matcher.h通用的RouteRuleMatcher模板基类被 basic_auth 等认证类插件复用负责规则匹配与global_auth语义plugin_test.cc覆盖配置解析成功/失败、重复凭证、全局认证开关、路由/域名授权、加密凭证、401/403 拒绝等 20 场景的单元测试BUILD声明basic_auth.wasm二进制目标BUILD与basic_auth_test测试目标BUILD当前插件版本为1.0.0见 VERSION。开发者若需本地验证可在plugins/wasm-cpp目录下按 Makefile 构建 wasm 产物并运行bazel test //extensions/basic_auth:basic_auth_test复现上述测试用例确认配置变更不会破坏既有行为。总结Higress 的basic-auth插件以极简的配置模型实例级consumers 规则级allow提供了标准、可靠的 HTTP Basic Auth 认证鉴权能力global_auth控制认证的作用范围路由/域名粒度规则决定细粒度授权X-Mse-Consumer头将调用者身份透传给下游服务而encrypted模式与多种密码哈希算法进一步提升了凭证存储安全性。结合本文的源码链路分析与错误码速查你可以在生产网关中快速完成 Basic Auth 的接入、灰度与故障定位。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考