Rodauth 是 Ruby 生态中一个功能非常完整的认证框架，它在 Roda 路由之上提供声明式配置，把登录、登出、注册、密码重置等功能统一管理。值得注意的是，Rodauth 还内置了 OAuth 2.0 提供方能力，通过 oauth 系列插件可以快速搭建一个同时支持授权码模式、隐式模式、客户端凭证模式的服务端。对于需要向第三方应用开放用户资源的场景，授权码模式是推荐的选择，因为令牌不会直接暴露在前端，而是通过后端通道完成兑换。配合 PKCE 扩展，即使客户端无法安全保管密钥，也能有效阻止授权码被截获后冒用的风险。本文会以 Rodauth 为基础，拆解授权码模式与 PKCE 的实现流程。
在 Rodauth 中启用 OAuth 2.0 能力并不需要从零编写令牌生成与校验逻辑，框架已经把这些流程抽象成插件和配置项。开发者需要关注的是三件事：定义客户端应用、挂载授权与令牌端点、配置 PKCE 挑战策略。下面从原理和代码两个层面展开说明。
一、授权码模式在 Rodauth 中的底层流程
授权码模式的第一个关键点在于把用户身份确认与令牌发放拆成两个独立请求。用户首先在客户端应用里点击登录，浏览器跳转到授权端点 /oauth/authorize，携带 response_type=code、client_id、redirect_uri、scope 等参数。Rodauth 会校验这些参数，确认客户端是否存在、重定向地址是否与注册时一致。如果用户尚未登录，Rodauth 会先触发登录流程，登录成功后再回到授权页面。
用户点击授权后，Rodauth 生成一个短期有效的授权码，并把授权码拼接到 redirect_uri 的查询参数中，让浏览器跳转回客户端。客户端拿到授权码后，在服务器端用 HTTP POST 请求令牌端点 /oauth/token，提交 grant_type=authorization_code、code、redirect_uri、client_id 等。Rodauth 校验授权码是否属于该客户端、是否未过期、是否已被使用，通过后发放访问令牌和可选的刷新令牌。
这种设计的核心优势是授权码通过浏览器地址栏传递，但访问令牌只通过后端请求返回。即使授权码被日志记录或浏览器历史泄露，只要攻击者没有客户端密钥，也很难直接兑换令牌。对于服务端渲染的传统 Web 应用，令牌可以存放在会话或服务端存储中，前端完全不接触。
二、PKCE 扩展解决的问题与 S256 挑战原理
PKCE 的全称是 Proof Key for Code Exchange，它的目标是防止授权码被拦截后由攻击者兑换令牌。授权码模式假设客户端拥有 client_secret，因此令牌请求需要携带密钥。但单页应用、移动端 App 这类公共客户端无法安全保存密钥，攻击者可能从客户端代码中提取密钥。没有 PKCE 时，授权码一旦在重定向过程中被截获，攻击者可以拿着授权码和自己的或受害者的 client_id 去令牌端点兑换。
PKCE 在授权请求中额外引入 code_challenge 和 code_challenge_method 两个参数。客户端首先生成一段随机字符串 code_verifier，长度为 43 到 128 个字符，然后使用 SHA-256 对 verifier 做哈希，再进行 Base64URL 编码得到 code_challenge。授权请求携带 challenge 和 method=S256，Rodauth 把这两个值与授权码关联存储。令牌请求时客户端提交 code_verifier，Rodauth 用同样的算法计算哈希并与存储值比对，一致才发放令牌。
Rodauth 的 oauth_pkce 插件提供了这套校验逻辑。默认情况下建议只允许 S256 方法，因为 plain 方法中 challenge 就是 verifier 本身，如果请求被中间人看到，攻击者可以同时拿到 verifier 和授权码，防护效果大打折扣。plain 只适合无法实现 SHA-256 的旧客户端，或者在开发环境中临时使用。
三、在 Rodauth 项目中启用授权码模式与 PKCE
首先在 Gemfile 中加入 rodauth 和对应的数据库适配器，然后执行迁移创建 OAuth 相关表。需要创建 oauth_applications 表保存客户端信息，至少包含 name、client_id、client_secret、redirect_uri、scopes 等字段；还需要 oauth_grants 表保存授权码、code_challenge、code_challenge_method、expires_at 等临时数据。Rodauth 的默认列名可以通过配置项修改，但保持默认约定能减少工作量。
下面是一段典型的 Rodauth 配置，启用了 OAuth 授权码模式和 PKCE，并指定 S256 为唯一允许的挑战方法。
plugin :rodauth do enable :login, :logout enable :oauth_authorization_code_grant enable :oauth_pkce # 客户端应用表与授权码表 oauth_applications_table :oauth_applications oauth_grants_table :oauth_grants # 授权码与重定向地址字段 oauth_grants_code_column :code oauth_grants_redirect_uri_column :redirect_uri # PKCE 相关字段 oauth_grants_code_challenge_column :code_challenge oauth_grants_code_challenge_method_column :code_challenge_method # 只允许 S256，禁止 plain oauth_pkce_code_challenge_methods ["S256"] # 令牌有效期，单位秒 oauth_grants_expires_in_column :expires_in oauth_grants_expires_in 600 end
配置完成后需要在 Roda 路由中挂载授权端点和令牌端点。Rodauth 插件会为每个功能生成对应的路由方法，常见写法如下。
route do |r|
r.rodauth
r.on "oauth" do
r.is "authorize" do
rodauth.oauth_authorize
end
r.is "token" do
rodauth.oauth_token
end
end
end
客户端发起授权请求时，地址类似 /oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=read&code_challenge=CODE_CHALLENGE&code_challenge_method=S256。Rodauth 会先校验所有参数，然后渲染授权表单让用户确认。授权完成后跳回 redirect_uri，并在查询参数中附带 code 和 state。令牌端点接收 POST 请求，参数包括 grant_type、code、redirect_uri、client_id 以及 code_verifier。如果校验通过，返回 access_token、token_type、expires_in 等 JSON 数据。
四、安全校验与常见配置误区
启用授权码模式后，重定向地址校验是安全的第一道防线。Rodauth 要求授权请求中的 redirect_uri 必须与客户端注册时填写的地址完全一致，不能使用子字符串匹配或模糊匹配。如果允许通配符，攻击者可能注册一个恶意客户端，通过开放重定向让授权码流向攻击者控制的地址。因此客户端注册时应当使用精确 URL，并在令牌请求中再次校验 redirect_uri 是否与授权码绑定的地址一致。
另一个容易被忽略的地方是授权码的一次性。Rodauth 会在授权码成功兑换令牌后将其标记为已使用或直接删除，防止同一个授权码被重放。如果令牌请求失败，例如网络超时导致客户端没有收到响应，客户端不应重复使用旧授权码，因为授权码可能已经被消费。正确的做法是重新发起授权流程。
对于 PKCE，配置上要避免把 plain 留在生产环境。部分开发者为了调试方便暂时允许 plain，但上线时忘记收紧策略，这会让 PKCE 的保护失效。建议在环境变量中控制可允许多种方法，开发环境放宽，生产环境只允许 S256。另外 code_verifier 的随机性也很重要，必须使用加密安全随机数生成器，不能使用时间戳或简单递增字符串。