请求到达后端前先验JWT：API Firewall的OAuth 2.0令牌校验与Scope匹配-二趣网

请求到达后端前先验JWT：API Firewall的OAuth 2.0令牌校验与Scope匹配

【免费下载链接】api-firewallFast and light-weight API proxy firewall for request and response validation by OpenAPI specs.项目地址: https://gitcode.com/gh_mirrors/ap/api-firewall

API Firewall是一款快速、轻量的 API 代理防火墙，除了基于 OpenAPI 规范校验请求和响应外，还能在请求到达你的后端服务之前，先完成OAuth 2.0 访问令牌的 JWT 校验和Scope 权限匹配。这意味着伪造签名、已过期或权限不足的请求，会在入口处被直接拦截，你的业务代码从此不用再自己解析令牌、操心鉴权。

为什么要在后端之前拦截无效令牌？

传统做法是请求先进入后端应用，再由应用里的鉴权中间件解析 JWT、查 scope。问题在于：

❌ 伪造或过期的令牌已经消耗了你的计算资源；
❌ 每个微服务都要重复实现一遍鉴权逻辑；
❌ 权限校验散落各处，安全审计困难。

API Firewall 把这一层前移：请求先到达防火墙，防火墙验证令牌合法性与权限后，才转发给受保护的后端。对新手来说，相当于给整个 API 系统装上了一道"门卫"。

💡 该功能仅在REST API 模式（按 OpenAPI 规范过滤请求）下可用。

JWT 校验的三步流程

当令牌校验类型设为JWT时，防火墙对每个请求执行三道检查（源码见internal/platform/oauth2/jwt.go）：

验证签名—— 使用你提供的 RSA 公钥（RS256/RS384/RS512）或 HMAC 密钥（HS256/HS384/HS512）验证令牌没被篡改；
验证有效期—— 解析 JWT 的exp声明，过期令牌直接拒绝；
匹配 Scope—— 把令牌中携带的scope声明与 OpenAPI 规范里该端点要求的 scope 逐一比对，缺一个就拒绝。

第 3 步是关键：OpenAPI 规范里声明了端点需要的权限，令牌里声明了调用者实际拥有的权限，两者一致才放行。这就是"Scope 匹配"的含义。

⚠️ 注意：API Firewall 不支持 ECDSA 算法签名的 JWT，选型时请优先使用 RS 或 HS 系列。

两种校验方式怎么选？

对比项	JWT 本地校验	Token Introspection 内省
适用场景	标准 JWT 令牌	非 JWT 令牌（Opaque Token 等）
工作方式	防火墙用公钥/密钥本地验签	防火墙远程调用你的令牌内省接口查询令牌元数据
性能	快，无网络往返	有缓存兜底：相同令牌默认10 分钟内直接读缓存，不重复请求内省接口
需要提供的东西	公钥`.pem`文件或 HMAC 密钥	内省接口地址、令牌参数名等

如果你用的是 Google OAuth、Gluu 等标准提供方且令牌是 JWT，选 JWT 模式；如果是自研的令牌体系，用 Introspection 模式对接你现有的内省端点即可。

快速配置：核心环境变量一览

以 Docker 方式部署时，只需设置以下几组环境变量（完整清单见 docs/configuration-guides/validate-tokens.md）：

环境变量	说明
`APIFW_SERVER_OAUTH_VALIDATION_TYPE`	校验类型：`JWT`或`INTROSPECTION`
`APIFW_SERVER_OAUTH_JWT_SIGNATURE_ALGORITHM`	JWT 签名算法，如`RS256`、`HS256`
`APIFW_SERVER_OAUTH_JWT_PUB_CERT_FILE`	RSA 公钥文件路径（RS 系列算法用，需挂载进容器）
`APIFW_SERVER_OAUTH_JWT_SECRET_KEY`	HMAC 密钥（HS 系列算法用）
`APIFW_SERVER_OAUTH_INTROSPECTION_ENDPOINT`	令牌内省接口地址
`APIFW_SERVER_OAUTH_INTROSPECTION_REFRESH_INTERVAL`	内省结果缓存时长，默认`10m`

同时，防火墙会读取规范中的securitySchemes来决定端点所需 scope，所以请在 OpenAPI 规范里如实填写每个端点的授权要求——这是 Scope 匹配的数据来源。

BLOCK 与 LOG_ONLY：先观察还是直接拦？

通过APIFW_REQUEST_VALIDATION变量控制防火墙对无效令牌的处理策略：

🛑BLOCK：直接拦截无效令牌的请求，适合生产环境上线；
📝LOG_ONLY：只记录不拦截，适合刚启用校验时先观察日志，确认规则无误后再切换到 BLOCK，避免误伤合法流量。

建议新接入时先用LOG_ONLY跑几天，再切到BLOCK。

源码导航：想看实现往哪走？

令牌校验接口定义：internal/platform/oauth2/oauth2.go
JWT 验签与 Scope 匹配实现：internal/platform/oauth2/jwt.go
Introspection 内省调用与令牌元数据缓存：internal/platform/oauth2/introspection.go
OAuth 相关配置结构（默认值如默认算法RS256、缓存10m）：internal/config/backend.go
APIMode 请求校验主流程（缺失 Authorization 头会报missing Authorization header）：pkg/APIMode/validator/
官方配置文档：docs/configuration-guides/validate-tokens.md
演示环境（含 docker-compose 配置）：demo/docker-compose/

小结

用一句话概括 API Firewall 的令牌校验能力：请求先过防火墙，防火墙先验 JWT 再放行。配置几个环境变量，就能把签名验证、过期检查、Scope 权限匹配全部下沉到入口层，后端应用专注业务逻辑。配合LOG_ONLY观察模式和 Introspection 缓存机制，这套方案既稳妥又高效，非常适合作为新手理解 API 网关鉴权的第一个实践项目。

【免费下载链接】api-firewallFast and light-weight API proxy firewall for request and response validation by OpenAPI specs.项目地址: https://gitcode.com/gh_mirrors/ap/api-firewall

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析