OAuth 2.0 协议规定客户端可以请求撤销访问令牌和刷新令牌，RFC 7009 描述了撤销端点，但协议本身并不关心撤销背后的原因。真正的业务系统里，撤销原因非常重要：是用户主动退出、会话过期、账号被盗后的应急处理，还是检测到刷新令牌重放攻击？如果只用一个 revoked_at 时间戳或 revoked 布尔字段记录状态，后续安全审计时很难还原具体场景。Rodauth::OAuth 的 TokenRevocationReason 正是为解决这个问题而设计的一组约定，它把常见的撤销动机变成结构化常量，并允许在撤销流程中把原因写入持久层。
该模块并不是一个复杂的抽象类，而是以常量集合的形式把撤销语义固定下来。这样做的好处是，开发者在调用撤销接口时不必自行拼写字符串，避免了大小写不一致、缩写混乱等问题。同时，因为原因值可枚举，数据库查询和统计也就有了稳定的分组维度。
一、令牌撤销原因往往被忽略
很多 OAuth 实现只关注撤销动作本身，认为只要把令牌标记为无效就完成了任务。这种思路在小型系统里或许可行，但当系统接入多个客户端、多个管理员角色之后，撤销原因就会成为安全审计的关键证据。比如一次批量撤销操作如果没有原因记录，就无法判断是正常的定期清理，还是因为某个客户端密钥泄露而进行的紧急处置。
从合规角度看，GDPR 和等保相关要求都强调对访问凭证的全生命周期管理。访问令牌属于临时凭证，刷新令牌则拥有更长的有效期，撤销刷新令牌相当于终止了用户会话的延续能力。如果日志里只记录一条“已撤销”，审计人员就无法回答“谁在什么时候因为什么原因撤销了哪个令牌”这样的问题。
Rodauth::OAuth 的设计者显然考虑到了这一点。TokenRevocationReason 模块预设了若干常见原因，例如访问令牌自然过期、刷新令牌重复使用、用户主动退出登录、管理员后台强制下线、令牌轮换以及客户端主动撤销等。每一个原因都对应一个简短但语义明确的字符串值，方便机器读取和人工排查。
module Rodauth
module OAuth
module TokenRevocationReason
ACCESS_TOKEN_EXPIRED = "access_token_expired"
REFRESH_TOKEN_REUSE = "refresh_token_reuse"
USER_LOGOUT = "user_logout"
ADMIN_REVOKED = "admin_revoked"
TOKEN_ROTATION = "token_rotation"
CLIENT_REVOKED = "client_revoked"
SESSION_TIMEOUT = "session_timeout"
ACCOUNT_SUSPENDED = "account_suspended"
end
end
end
这些常量值设计得很克制，全部采用小写字母加下划线的形式，既方便存入数据库，也能直接出现在 JSON 响应或日志字段中。开发团队可以根据业务需要扩展新的原因，但核心思路是保持值的一致性。
二、TokenRevocationReason 模块与数据库持久化
要在 Rodauth 应用中真正记录撤销原因，光有常量还不够，还需要在数据库层预留对应字段。通常做法是在 oauth_grants 表上增加 revocation_reason 和 revoked_at 两个字段。前者保存原因字符串，后者记录撤销发生的时间。如果系统已经使用 revoked 布尔字段，也可以保留它作为快速过滤条件。
下面的 Sequel 迁移展示了如何为已有的 OAuth 授权表增加撤销原因字段。添加索引是一个容易被忽略的细节，因为后续审计查询经常需要按原因分组统计，没有索引时全表扫描会拖慢后台管理页面。
Sequel.migration do
change do
alter_table(:oauth_grants) do
add_column :revocation_reason, String, null: true
add_column :revoked_at, Time, null: true
add_index :revocation_reason
end
end
end
执行迁移之后，撤销令牌的代码就不能只更新 revoked 字段了。比较稳妥的方式是封装一个仓库方法，在写入前校验传入的原因是否属于 TokenRevocationReason 模块中定义的合法值。这样做可以拦截拼写错误，避免脏数据进入数据库。
class OAuthGrantRepository
def revoke_with_reason(grant, reason)
valid_reasons = Rodauth::OAuth::TokenRevocationReason.constants.map do |name|
Rodauth::OAuth::TokenRevocationReason.const_get(name)
end
unless valid_reasons.include?(reason)
raise ArgumentError, "Unknown revocation reason: #{reason}"
end
grant.update(
revoked_at: Time.now.utc,
revocation_reason: reason
)
end
end
这段代码通过反射读取模块中的常量值，再用 include? 判断传入值是否合法。虽然反射会在启动阶段带来一点性能开销，但对于低频的撤销操作来说完全可以接受。更重要的是，它把原因校验集中在了一个地方，调用方无法随意写入诸如“手动删了”这类无结构化的文本。
三、典型场景下的撤销原因映射
撤销原因的价值只有在真实场景中才能体现出来。以刷新令牌重用检测为例，OAuth 2.0 规范建议当同一个刷新令牌被多次使用时，授权服务器应当撤销所有关联令牌，因为这种情况很可能意味着令牌已经被攻击者截获。此时写入 REFRESH_TOKEN_REUSE 就是最合适的做法，后续安全团队可以根据这个原因快速定位可能受影响的用户。
用户主动退出登录时，系统一般会撤销当前访问令牌和刷新令牌。此时原因可以标记为 USER_LOGOUT。如果用户因账号被盗而由管理员强制下线，则应使用 ADMIN_REVOKED 或 ACCOUNT_SUSPENDED，以便在审计日志中区分正常用户行为与安全事件处置。
下面列出几种常见映射关系，供接入时参考：
- 访问令牌超过有效期限：
ACCESS_TOKEN_EXPIRED - 刷新令牌被重复使用：
REFRESH_TOKEN_REUSE - 用户点击退出登录：
USER_LOGOUT - 管理员在后台强制下线：
ADMIN_REVOKED - 令牌轮换过程中旧令牌作废：
TOKEN_ROTATION - 客户端主动发起撤销请求：
CLIENT_REVOKED
当原因被规范记录之后，统计不同撤销原因的分布就变得非常简单。例如使用 Sequel 可以按原因分组统计，输出结果可以用于安全月报或异常检测。
# 使用 Sequel 统计不同撤销原因的数量
DB[:oauth_grants]
.where { revoked_at !~ nil }
.group_and_count(:revocation_reason)
.all
.sort_by { |row| -row[:count] }
.each do |row|
puts "#{row[:revocation_reason] || "unknown"}: #{row[:count]}"
end
这段查询结果可以直接接入监控面板。如果某段时间内 REFRESH_TOKEN_REUSE 数量突然升高，很可能意味着存在针对刷新令牌的批量攻击，运维人员可以据此触发告警。相较之下，只记录布尔状态是无法发现这类异常模式的。
四、避免硬编码与审计查询最佳实践
即使有了 TokenRevocationReason 常量，实际项目中仍然容易出现硬编码问题。有的开发者在调用撤销方法时图省事，直接传入字符串字面量，例如 grant.update(revocation_reason: "user_logout")。这种写法在单个项目里看似没有问题，但随着代码规模扩大，同一个原因可能以不同大小写或拼写形式出现，最终导致统计结果失真。
下面这段代码就是典型的反例：同一个业务含义被写成了四种不同形式。如果这些都进入数据库，后续按原因分组会产生多个无意义的分组，审计查询需要额外清洗数据。
# 容易导致数据不一致的写法 grant.update(revocation_reason: "user_logout") grant.update(revocation_reason: "UserLogout") grant.update(revocation_reason: "USER_LOGOUT") grant.update(revocation_reason: "user logged out")
正确做法是在所有需要撤销令牌的地方统一调用封装好的仓库方法，并强制传入 TokenRevocationReason 中的常量。这样可以在代码审查阶段就拦截不一致的写法，也能通过 IDE 自动补全降低拼写错误概率。
另外，撤销原因字段应保持短小精悍，避免写入过长的自然语言描述。数据库字段长度可以设置为 64 或 128 字符，这样既能容纳扩展后的原因值，又不会给表带来过多存储压力。日志系统在记录撤销事件时，可以直接拼接原因值和用户标识，但如果要输出到第三方安全平台，需要注意对用户信息做脱敏处理。
最后建议在后台管理页面中增加撤销原因筛选器，让管理员能够按原因查看被撤销的令牌列表。结合 revoked_at 时间范围，可以快速回答“上周因管理员强制下线撤销了多少令牌”这类问题。Rodauth::OAuth 的 TokenRevocationReason 提供的是语义基础，而实际审计效果取决于持久化和查询是否规范。
Rodauth::OAuth令牌撤销TokenRevocationReason修改时间：2026-09-28 02:31:58