我去年接手了一个餐饮优惠聚合平台的接口服务对外要对接好几家外卖平台和本地商户的开放 API对内要给小程序和 App 提供统一入口。这个服务在内部被伙伴们习惯性称为“霸王餐 API”——因为它整天处理的就是优惠权益聚合、订单核销和状态同步这类事情。一开始我图省事整套鉴权就用单一 JWT 签发代码量最少联调也快。但真正把流量跑起来、第三方商户开始接入之后问题一个接一个冒出来token 泄露没法主动作废、刷新逻辑要靠每个调用方自己实现、同一个请求分不清是哪个商户哪个用户发起的。被逼着重构之后我选用了 OAuth2.0 JWT 的双令牌机制才把这套对外接口的鉴权从“能用”捞回到“敢用”。这篇内容不打算空谈概念全部是我在 Java 环境里实现这套机制时的真实决策和踩坑记录。如果你也在做类似的外部接口对接——不管是餐饮、电商还是任何需要开放 API 给第三方调用的系统——可以参考这套方案再结合自己的业务做裁剪。我会把选型理由、整体设计、服务端签发校验、第三方调用细节、多实例部署状态同步这些环节都铺开讲尽量做到每一步都知道“为什么这么做”。1. 为什么双令牌机制比“一把 JWT 走天下”更适合第三方对接先说结论不是所有场景都需要 OAuth2.0 JWT 双令牌。纯内部的几个微服务之间调用用 mTLS 或者更轻的内部签名就够。但一旦接口要开放给第三方——尤其是外卖、电商这种“多个商家/多个平台互相调”的生态——双令牌机制的优势就非常明显了。1.1 单一 JWT 在对外场景下的三个硬伤第一个硬伤也是我最早踩到的JWT 签完之后在没有黑名单机制的默认情况下服务端是没法在过期之前主动让它失效的。JWT 是自包含、无状态的校验方拿到手验个签名、看个 exp 就觉得“这是一张合法票据”。内部服务之间用无所谓出了问题可以直接重启或改配置但第三方拿着 token 调你的接口你就算发现 token 已经泄露也只能干瞪眼等到 exp 自然到达。第二个硬伤是刷新语义缺失。JWT 的规范里只有签发生命周期的概念它不负责告诉你不“怎么续”。如果你只是简单地做“过期了就重新签一个”那等于每次调用都要重新走一遍授权流程OAuth2.0 那套授权码、刷新令牌的机制就完全没有意义了。我在第一个版本里就是这么干的结果就是第三方接入方自己写了一个“定时重新登录”的逻辑密码散落在各家商户的代码仓库里想想都后背发凉。第三个硬伤是身份层次被压平了。对外接口的鉴权实际上有两层身份需要区分调用方应用身份哪家商户、哪个平台在调和业务用户身份这次操作是对哪个用户的哪笔订单。单一 JWT 如果全塞进去claims 会越来越大而且签发者也很难按调用方去控制权限范围。你给商户 A 的 token他完全可以拿去当商户 B 的凭证用如果字段设计得不严谨连排查都无从下手。1.2 分工明确的组合OAuth2.0 管授权JWT 管身份双令牌机制的核心思路其实很简单OAuth2.0 负责“授权流程”JWT 负责“身份载体”。两者各干各的并不冲突。拿 OAuth2.0 的四种角色来看资源所有者用户、客户端第三方应用、授权服务器我们、资源服务器我们的 API。授权服务器签发出 access token 和 refresh token客户端拿着 access token 去访问资源服务器access token 过期后用 refresh token 去换新的。access token 用什么格式用 JWT。这样资源服务器只需要做无状态验签连查询数据库都不需要就能确认这个请求是谁发来的、有哪些权限。打个比方access token 就像一张“临时门禁卡”刷一下就能进门但有效期只有十几分钟refresh token 则是你的“身份证明文件”门禁卡过期了拿身份证明文件去前台换一张新的。门禁卡丢了最多损失十几分钟的使用窗口身份证明文件丢了前台会立即帮你挂失、作废换一张新的。这就是双令牌机制的精髓把短时效凭证放在业务链路上把长时效凭证藏在最安全的地方。1.3 这套组合不适合哪些场景说完了适合也得说说不适合免得有人过度设计。如果你的系统只有几个内部微服务服务之间用 HTTP 调用那架双令牌机制反而拖慢性能、增加复杂度。比如 A 服务要调 B 服务之间走内网直接上 mTLS 双向认证或者用简单的内部 HMAC 签名就够了如果你做的是开放平台但调用方只有两三个核心客户也可以用 API Key 加签名的方式没必要把 OAuth2.0 整套流程跑起来。我判断标准就一条你的“调用方”是不是一个动态扩展的集合。如果是那必须上双令牌如果永远是固定的那三五个内部模块别折腾选简单方案。当年的我如果早想清楚这个标准也不会在第一版就把单一 JWT 用到第三方接口上。2. 认证闭环的整体设计先想清楚令牌关系再动手很多人一上来就写Jwts.builder()这是大忌。在我重构的第二周我花了一整天先画令牌关系图——不是流程图就是在一张白纸上列出“谁持有谁”“谁签发谁”“谁校验谁”。这一步想清楚了后面写代码就是体力活。2.1 四类令牌的角色分配我在最终方案里实际上用到了四类凭证它们各管一摊凭证类型格式有效期持有方用途client_id / client_secret字符串对长期第三方应用标识调用方应用身份换取 access tokenaccess tokenJWT15 分钟第三方应用访问业务接口的短期凭证refresh token不透明随机串7 天第三方应用服务端存摘要在 access token 过期后换取新的 access token内部 HMAC 签名请求头签名一次有效我们自己的服务服务间兜底防止纯内网请求被伪造这里要注意前三种是 OAuth2.0 的标准角色第四种是我额外加的。因为我们的合作伙伴里有些是传统餐饮商户技术能力参差不齐有的商户会直接把 access token 放在日志打印里。我在网关层又加了一层内部 HMAC 签名即使 token 被第三方 Log 平台抓走了攻击者想伪造请求体也比较困难。2.2 令牌字段与生命周期设计access token 里我放了一套精简后的 claims原则是“只放公共标识不放敏感信息”。你永远不应该在 JWT 里塞手机号、余额、身份证这类东西因为 JWT 默认只是 Base64Url 编码并不是加密。我用过的最接近敏感的东西也就是order_id和shop_id而且这两个字段也是业务上需要做权限拦截的维度。我的 claims 设计大致是iss固定为我们的授权服务器标识sub第三方应用的 client_idjti令牌唯一 ID用于黑名单aud固定为 API 网关地址标识scope权限范围如order:read、order:writeuser_id当前操作针对的用户 IDshop_id当前操作针对的商户 IDiat/exp签发时间和过期时间生命周期我调过好几轮最终定下来的组合是 access token 15 分钟、refresh token 7 天。15 分钟是个折中值太长泄露后的风险窗口大太短第三方调接口时刷新太频繁体验很差。7 天的 refresh token 周期配合“轮换机制”也就是每次刷新都发一个新的 refresh token旧的同时作废这样即使某个 refresh token 泄露也不会被长期反复使用。2.3 为什么 access token 用 JWT、refresh token 不用这是个被问烂了但很多人还是搞混的问题。我的答案是access token 需要被资源服务器验签且通常是无状态的所以用 JWTrefresh token 只和授权服务器对话不需要被任何第三方解析所以用不透明随机串反而更好。refresh token 如果用 JWT会带来两个问题一是无法主动撤销——你发出去的 JWT就算存进数据库第三方还是能拿着它来换新的 access token二是它里面会携带一些授权信息暴露在第三方手里并不是好事。用不透明随机串服务端只需要存一个哈希摘要撤销时直接删记录生效是即时的。3. 服务端签发与校验JWT 生成逻辑中的几个关键决策这一节是纯 Java 落地过程。我自己用的是 Spring Boot 3.xJWT 库用的jjwt 0.12.x。如果你用的是 Spring Boot 2.xAPI 略不同但思路完全一样。3.1 签名算法选 RS256 而不是 HS256这是我在第一版代码里就做出的选择后来证明非常关键。HS256 是 HMAC 对称签名签发和校验用的是同一个密钥RS256 是 RSA 非对称签名签发用私钥校验用公钥。为什么第三方接口场景必须用 RS256两个原因。第一验签服务的私钥接触面越小越好。资源服务器或 API 网关只需要拿到公钥就能验签私钥只存在授权服务器一个地方。如果哪个实例被拖了公钥泄露了也无所谓它只能验签不能签发。第二密钥轮换更灵活。配合 JWKSJSON Web Key Set你可以把公钥挂在一个 HTTPS 端点/jwks上验签方定期去拉取。轮换私钥时公钥端点同时更新验签方不用改任何代码。生成密钥对可以用 OpenSSL# 生成 RSA 私钥2048 位 openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048 # 导出公钥 openssl pkey -in private_key.pem -pubout -out public_key.pem然后把私钥放在授权服务器的配置中心公钥放在 API 网关的配置里或者挂到 JWKS 端点。注意私钥权限必须收紧不能打进 Docker 镜像、不能进 Git 仓库。3.2 密钥轮换与 kid 设计密钥不会永远安全所以轮换是必须的。我的做法是每次生成新密钥对时给它分配一个kid签发 JWT 时把kid写进 header。验签方拿到 JWT 后先看 header 里的kid去公钥列表里找到对应密钥来验签找不到就直接拒绝。这里顺带说一个安全要点——kid字段必须限定白名单否则容易被人利用做“密钥注入”。有几种常见的攻击套路攻击者把alg改成none绕过签名校验或者把alg从RS256改成HS256骗你用 RSA 公钥作为 HMAC 密钥来验签还有kid被塞入不可信值导致程序加载了攻击者控制的“公钥”。在 Java 里用 jjwt 时底层库默认会校验alg但你自己写的验签逻辑不能完全依赖它。我的做法是在解析前先检查 header 里的kid是否存在于数据库白名单中不在直接返回 401。签发 JWT 的示例代码// 加载 RSA 私钥 PrivateKey privateKey loadPrivateKey(...); // 设置 access token 过期时间15 分钟 Instant now Instant.now(); Instant expiry now.plus(15, ChronoUnit.MINUTES); String accessToken Jwts.builder() .issuer(platform-auth-server) .subject(clientId) .audience().add(api-gateway).and() .id(UUID.randomUUID().toString()) .claim(scope, order:read order:write) .claim(user_id, userId) .claim(shop_id, shopId) .issuedAt(Date.from(now)) .expiration(Date.from(expiry)) .header().keyId(key-2024-01).and() .signWith(privateKey, Jwts.SIG.RS256) .compact();3.3 校验逻辑四类恶意场景必须拒之门外校验逻辑是双令牌机制的安全底线。我写了一个OncePerRequestFilter每个请求进来先走它只做三件事验签、查过期、查黑名单。在这个过滤器里我会主动拒绝以下几类场景第一alg为none或缺失。这是最原始的绕过手段任何验签步骤都不能接受无签名的 JWT。第二算法混淆。如果请求头声明alg: HS256而系统期望的是RS256直接拒绝。实现上可以不管是 验签 还是 解析都必须显式指定期望算法不能从 header 里“自适应”选择。第三签名密钥不符。用kid对应的公钥验签失败立即拒绝不要 fallback 到别的密钥再试一次。第四jti命中黑名单。即使签名合法、未过期如果这个令牌被主动吊销过也要拒绝。一个精简的校验代码JwsClaims jws; try { jws Jwts.parser() .verifyWith(publicKey) .requireIssuer(platform-auth-server) .build() .parseSignedClaims(token); } catch (JwtException e) { throw new UnauthorizedException(invalid token, e); } Claims claims jws.getPayload(); // 1. 校验 scope if (!containsRequiredScope(claims, requiredScope)) { throw new ForbiddenException(insufficient scope); } // 2. 校验 jti 黑名单 if (isBlacklisted(claims.getId())) { throw new UnauthorizedException(token revoked); }这套校验逻辑跑在 API 网关层同一个网关服务了所有业务接口。校验过程全是本地验签没有一次数据库查询压力大的时候完全扛得住。4. 第三方接口调用的落地细节拿到令牌后怎么用才不容易翻车服务端签发说完了接下来是最容易被忽略的另一半——第三方调用端怎么安全地持有和使用这些令牌。我在对接合作商户时发现第三方接入方对安全的理解天差地别所以我们把调用端的 SDK 做得很重把这套逻辑直接封装进去不让商户自己造轮子。4.1 令牌的存储与加载client_id和client_secret这一类长期凭证不要在代码里硬编码也不要放进能被前端下载的包里。我的建议是放到环境变量或者配置中心运行期加载到内存。access token 和 refresh token 也不要落库。商户的 SDK 里我设计成两个可选的存储后端单机部署时用内存加文件持久化多实例部署时用 Redis。这里有个容易被忽视的问题进程重启之后refresh token 如果丢了等于让用户重新授权。第三方商户大半夜重启个服务第二天早上所有用户都收到“登录过期”这体验非常糟糕。所以我在文件持久化里做了加密存储虽然不能防止设备被完全控制后泄露但至少避免日志踢出明文 token 的尴尬。4.2 自动续期的两种策略我把续期策略做成双保险定时刷新 调用前懒刷新。定时刷新的逻辑是每隔一小段时间检查 token 剩余有效期如果剩余时间小于 5 分钟就提前刷新。为什么是 5 分钟因为 15 分钟的生命周期里最后 5 分钟是一个“衰减区”此时发起业务的成功率已经开始下降不如提前换新。懒刷新的逻辑更关键在每次发起调用前检查剩余时间如果小于 3 分钟就先刷新再调用。可能有人觉得这会导致很多冗余刷新请求实际上我用一个静态标记来控制并发只允许一个线程真正发起刷新其他线程等待结果即可。4.3 并发刷新双令牌机制最经典的坑这是我在调测阶段踩得最深的一个坑。场景是这样的SDK 里 30 个线程同时发现 token 还剩 30 秒到期缓存里存的这个 token 已经失效了。线程集体冲向刷新接口然后全部传入同一个 refresh token。如果授权服务器严格实现“refresh token 轮换”——也就是每次刷新后旧 refresh token 立即作废——那么这 30 个请求中最多一个成功剩下 29 个全部收到“refresh token 已被使用”的报错。解决思路是加一个进程内的刷新锁。我用AtomicBoolean加双重检查保证同一时刻只有一个线程执行刷新逻辑private final AtomicBoolean refreshLock new AtomicBoolean(false); public String getAccessToken() { long remaining accessTokenExpiry - System.currentTimeMillis(); if (remaining 3 * 60 * 1000L) { return accessToken; // 剩余时间大于3分钟直接用 } if (refreshLock.compareAndSet(false, true)) { try { // 这里真正发起刷新 refreshAccessToken(); } finally { refreshLock.set(false); } } // 其他线程等待刷新完成拿新 token return waitForLatestAccessToken(); }如果你是多实例部署进程内的锁就不够用了要在授权服务器端用 Redis 做“单次刷新”逻辑。我后面会细说。4.4 401 重试的幂等设计还有一个细节第三方接口调用返回401 Unauthorized时很多 SDK 会“果断重试”结果造成请求风暴。我设计了一个很保守的重试策略遇到 401先读响应头里的错误码判断到底是 token 过期、token 被吊销还是 client 本身就没权限。只有明确是 token 过期时才触发一次刷新然后重试一次业务请求。重试前给每个请求生成一个request_id放在请求头里用于服务端幂等判断。重试两次仍失败直接抛异常不再继续死磕。幂等键的作用被很多人低估。在外卖场景里一次订单核销如果因为网络超时被重试两次可能会造成重复核销。我在核心写接口上强制要求调用方传幂等键服务端依据request_id shop_id user_id做去重效果显著。5. 多实例部署下共享令牌状态与审计我们授权服务器和生产 API 网关都是多实例部署这一节分享状态共享的方案。在这个阶段“无状态”已经不再是无状态了。为了安全我们必须引入一部分有状态存储。5.1 服务端必须用 Redis 管理三样东西我通过 Redis 管理三类数据refresh token 摘要、jti 黑名单、refresh token 轮换记录。refresh token 摘要存的是哈希值不存明文。这样即使 Redis 被拖库攻击者也无法用摘要换 token。jti 黑名单的 key 设计成black:jti:{jti}value 不需要真正存内容只需要占位。过期时间设置为原 token 剩余的有效期。这样即使一个 token 还有 10 分钟才过期我们将其加入黑名单后10 分钟后它自然从 Redis 消失不需要额外清理任务。refresh token 轮换记录比较复杂。因为多实例下即使进程内加了锁还是可能出现两个实例同时拿着旧 refresh token 来刷新的情况。我的设计是刷新接口收到旧 token 时先查 Redis如果存在“已轮换”标记就再给它一个 30 秒的宽限期允许它在宽限期内用一次返回跟上次刷新相同的 access token。这样两个并发刷新请求都能得到新 token不会冲突。5.2 令牌与请求指纹绑定防重放access token 是 JWT如果被网络抓包截获攻击者可以在有效期内反复使用。我在网关上要求每个请求必须携带两个额外东西X-Timestamp和X-Signature。签名是用 pre-shared key 对method path body timestamp做 HMAC 计算出来的。网关会拒绝时间偏差超过 5 分钟的请求每条签名也只能用一次。这套方案不能完全防住中间人流量劫持因为如果攻击者能实时转发请求它也能签名。但在实际业务里它至少挡住了“偷到 token 后离线重放”这条攻击路径。如果你对接的第三方技术能力比较弱连 HMA 签名都实现不好那就退而求其次只校验 timestamp 和 token 是否匹配把防重放降级到“弱校验”。5.3 审计日志与异常检测我做了两张核心审计表api_call_log和token_refresh_log。前者记录每个请求的调用方 client_id、访问路径、目标订单、响应码、耗时后者记录每次刷新动作哪个 client_id、哪个 refresh token 摘要、旧 token 摘要、新 token 摘要、从哪个 IP 发起。这两张表在安全事件发生时就是救命稻草。举个例子后来我们真的碰到过一家商户的 access token 泄露。从审计日志里我一眼就能拉出该 client_id 在泄露时间段内的所有请求再对比正常的调用频率和地理位置很快就定位到了异常流量然后直接在授权服务器端吊销那条用户链路对应的 refresh token。如果没有审计表这个过程只能靠猜。6. 加固后的实测效果与仍待解决的事改造上线后我做了两轮对比评估。第一轮是功能层面的用模拟流量打接口验证 token 过期后自动续期、并发刷新、黑名单吊销这几条链路是否稳定。第二轮是长期观察上线后跑了三周看了线上日志和告警数据。最直观的感受是出问题时定位速度比原来快了一个数量级。以前单一 JWT 的时候查询“是谁在调哪个接口”基本靠猜现在因为每个 access token 里有 claims 里的 client_id、shop_id、user_id配合审计日志一份 SQL 就能把整个调用链拉出来。之前发生过一次商户回调地址被刷的情况十分钟内我们就从日志里发现来源 IP 集中、user_id 乱跳及时封禁了那个 client_id整个过程没有影响其他商户。还有一组数据我觉得很能说明问题改造前线上每天因为“鉴权失败”的工单大概有七八个基本都是第三方说自己的 token 过期了、让商户重新配置密钥改造后这类工单趋近于零因为 SDK 自动续期把过期问题消化在了调用链路里。刷新失败和 401 重试的比例也大幅下降尤其是我加了进程内刷新锁之后刷新冲突的报错日志基本消失。当然这套方案不是万能药。我目前还在纠结几个遗留问题。第一个是 refresh token 有效期的问题——7 天对于店铺管理员来说太短但拉长到 30 天又怕泄露风险变大。我初步的想法是引入滑动过期机制只要用户在 7 天内有过活跃操作就自动续期一轮超过 7 天无活跃则作废。第二是细粒度权限现在 scope 只有order:read、order:write这种粗粒度接下来想按资源维度做成 ABAC 策略配合规则引擎做到更细的权限控制。第三是配额管理每个 client_id 的 API 调用上限目前是写死的配置后面想改成动态限流结合令牌桶算法和实时监控数据自动调阈值。最后分享一个我这几个月下来最深的体会双令牌机制的精髓不在于“多了一个 token”而在于把**“授权”和“身份”彻底拆开**。授权管的是“能不能进来”身份管的是“你是谁、能操作哪些资源”。想清楚这一层你会发现自己设计接口鉴权时突然有了章法——先问自己这个请求最需要确认什么再去决定用哪种令牌、放哪些 claims而不是上来就刷一把 JWT。希望这篇落地记录能帮正在做第三方接口对接的人少走几个弯路尤其是并发刷新那个坑真的值得提前防一下。