在设计Rodauth API认证时，访问令牌的有效期如果拍脑袋决定，后续维护成本会很高。Rodauth::JWTAuth把这个问题拆开：Bearer Token作为短期凭证，Refresh Token作为长期续期凭证，二者通过不同的过期周期和刷新轮换策略互相配合。下面先看Bearer Token本身的生成与校验链路。
Bearer Token的生成与校验链路
Rodauth::JWTAuth底层仍然使用JWT标准。用户通过login成功后，插件会在jwt_secret指定的密钥下生成一个短期JWT，其payload里包含账户标识、签发时间和过期时间等标准声明。该令牌默认通过Authorization: Bearer <token>请求头传给服务端，Rodauth在解析时会先做签名校验，再检查过期时间，最后加载对应账户。
启用JWT能力并不复杂，通常在plugin :rodauth块中开启:login和:jwt，然后设置密钥与过期策略。下面是一个最小配置示例。
plugin :rodauth do
enable :login, :logout, :jwt
jwt_secret { ENV.fetch("JWT_SECRET") }
jwt_access_token_period { 15 * 60 } # 15分钟
jwt_algorithm { "HS256" }
end
route do |r|
r.rodauth
r.on "api" do
rodauth.require_authentication
r.get "profile" do
response['Content-Type'] = 'application/json'
{ "email" => rodauth.current_account[:email] }.to_json
end
end
end
代码中的jwt_access_token_period控制Bearer Token的有效期，单位是秒。15分钟意味着即使令牌泄露，攻击者可以利用的时间窗口也很短。签名算法默认采用HS256，这是一种对称算法，服务端只需要保管一个密钥。认证成功后，客户端拿到的JSON响应通常包含访问令牌和刷新令牌两个字段，后续请求只带访问令牌即可。
校验环节里值得留意的是，Rodauth会优先处理Authorization头中的Bearer Token，而不会去查找Cookie。因此前端Web应用、移动端或第三方客户端都必须显式管理令牌存储与发送逻辑。服务端不需要维护访问令牌的状态，因为JWT本身已经携带了必要的上下文信息，这降低了分布式场景下的存储压力。
刷新令牌如何实现低打扰续期
刷新令牌的有效期通常比访问令牌长得多，比如7天或30天。它不能被用来直接访问业务接口，而是专门调用刷新端点换取新的访问令牌。这样设计的核心好处是：即使用户在访问令牌过期后，客户端也能在后台静默续期，不会打断使用体验。Rodauth::JWTAuth在刷新请求时同样会校验刷新令牌的签名、有效期和账户状态。
刷新请求一般在r.rodauth路由处理范围内自动注册，客户端向/jwt/refresh发送POST请求，并提供刷新令牌。插件验证成功后，会返回一组新的访问令牌和刷新令牌。下面是刷新请求的HTTP报文示例。
POST /jwt/refresh HTTP/1.1
Host: api.ipipp.com
Content-Type: application/json
{
"refresh_token": "dGhpc19pc19hX3JlZnJlc2hfdG9rZW4..."
}
响应体中会包含新的access_token和新的refresh_token。如果配置了轮换策略，旧刷新令牌会被标记为已使用或直接失效。这一点非常关键：没有轮换机制时，攻击者一旦拿到刷新令牌，就可以在令牌有效期内持续续期；有了轮换，攻击者和合法用户可能同时持有同一个旧刷新令牌，后使用的一方会暴露异常，服务端也能据此触发账户保护动作。
实际项目中建议开启刷新宽限时间。由于网络延迟和并发请求的存在，客户端可能在请求刷新后的极短时间内仍使用旧刷新令牌，如果服务端立刻作废旧令牌，容易导致误杀。Rodauth::JWTAuth允许设置一个短暂的宽限窗口，例如30秒，窗口内旧令牌仍可被识别但会触发告警日志，方便追踪是否存在重放。
生产环境必须关注的安全配置
密钥管理是JWT安全的第一道门槛。jwt_secret绝对不能硬编码在源码里，更不应该提交到版本库。推荐从环境变量或密钥管理服务中读取，并定期轮换密钥。对于对称算法HS256来说，密钥长度必须足够，通常建议使用32字节以上的随机字符串。如果团队需要更高的安全等级，可以考虑切换为RS256等非对称算法，让服务端持有私钥、验证方持有公钥。
另一个容易被忽视的问题是令牌存储位置。浏览器端如果把刷新令牌放在localStorage，一旦遭遇XSS攻击，令牌很容易被读取。更稳妥的方案是将访问令牌保存在内存中，将刷新令牌放在httpOnly、Secure的Cookie里，并配合CSRF防护。不过这会引入Cookie与Bearer模式混用的问题，需要根据API受众决定是否接受。对于纯服务端到服务端的调用，仍然建议使用严格的Bearer头传递。
令牌过期策略也建议与环境区分。开发环境可以设置较长的刷新令牌周期，便于调试；生产环境则应缩短访问令牌周期，同时为刷新令牌设置合理的绝对过期时间，避免一个令牌永久续期。Rodauth::JWTAuth还支持在账户登出或禁用时立即失效相关令牌，这些逻辑通常通过账户状态校验实现，具体可以在before_jwt_refresh等钩子中补充业务检查。
避免把这些做成定制轮子
不少团队一开始只打算写一个简单的JWT工具类，后来慢慢加入刷新、轮换、黑名单、并发处理等需求，最终维护成本反而超过直接使用成熟认证框架。Rodauth::JWTAuth的价值在于把这些常见需求统一到配置层，而不是让每个项目重复实现。尤其是刷新令牌轮换和宽限时间，这些细节如果自己实现，很容易在并发刷新时出现问题。
在选型时还需要注意，Bearer Token与Refresh Token并不是银弹。如果API仅提供给内部可信系统使用，且调用频率很低，或许更简单的API Key或短期JWT就够了。Rodauth::JWTAuth更适合面向Web前端或移动端的多客户端场景，它把认证从状态化Session中解放出来，同时保留可扩展的账户管理和审计能力。
最终落地之前，建议先用自动化测试覆盖令牌过期、刷新成功、旧令牌重放、签名错误等场景。这些测试比任何文档都更能发现配置遗漏，也能保证后续升级时不会破坏已有的认证行为。
Rodauth::JWTAuthBearer TokenAPI认证修改时间：2026-10-05 17:38:38