令牌机制与会话管理：JWT 与刷新令牌

令牌机制与会话管理：JWT 与刷新令牌

登录成功后，「登录态」靠什么维持？答案是令牌（Token）。Supabase Auth 采用业界主流的 JWT（JSON Web Token） 方案，配合刷新令牌实现长期会话。理解令牌机制，是排查认证问题、设计安全策略的关键。

什么是 JWT

JWT 是一种紧凑的、自包含的令牌格式，本质上是一段经过签名的字符串。它由三部分组成：

1. 头部（Header）：说明令牌类型与签名算法。
2. 载荷（Payload）：携带关于用户的关键信息，如用户 id、邮箱、过期时间、角色等。
3. 签名（Signature）：用密钥对头部与载荷签名，防止内容被篡改。

三部分用点号连接，形如 header.payload.signature。

JWT 的关键特性是自包含：令牌本身就携带了用户身份信息，服务端解析令牌即可知道「是谁」，无需每次都去查询数据库。这让它非常适合分布式、无状态的认证场景。

JWT 的签名与防篡改

JWT 的签名机制确保了「令牌一旦签发，任何人都无法伪造或篡改其内容」：

• 签发方用密钥对载荷签名，附加在令牌末尾。
• 接收方收到令牌后，用同样的密钥重新计算签名，与令牌中的签名比对。
• 两者一致，说明令牌内容未被篡改，可信；不一致则拒绝。

因此，保护 JWT 签名密钥的安全至关重要。在 Supabase 中，这个密钥由平台托管，开发者无需直接管理，但务必保管好项目密钥，不要泄露。

访问令牌与刷新令牌的分工

为了兼顾安全与体验，Supabase 采用「双令牌」模式：

• 访问令牌（Access Token，即 JWT）：有效期较短（通常几十分钟），用于日常请求鉴权。即使被窃取，危害时间窗口也有限。
• 刷新令牌（Refresh Token）：有效期较长（数天到数周），仅用于在访问令牌过期时换取新的访问令牌，不用于业务请求。

两者的协作流程如下：

这种设计让用户长期保持登录，同时把敏感令牌的有效期压到最短，是安全与体验的平衡。

令牌的生命周期与会话维持

一个完整的会话生命周期：

1. 登录：凭证校验通过，签发访问令牌与刷新令牌。
2. 正常请求：客户端携带访问令牌，服务端解析并据此鉴权。
3. 过期续期：访问令牌过期后，客户端用刷新令牌静默换取新令牌，用户无感。
4. 登出：销毁会话，令牌失效（刷新令牌被吊销）。
5. 长时间不活动：刷新令牌也过期时，用户需要重新登录。

Supabase 的客户端库会自动处理第 2、3 步——你登录一次后，库会在后台续期，开发者通常只在「需要判断登录状态」时关心令牌。

JWT 载荷里的角色信息

JWT 载荷中除了用户 id，还携带**角色（role）**信息，这在 Supabase 安全模型中至关重要：

• 未登录用户：角色为匿名（anon），受 RLS 对匿名策略约束。
• 已登录用户：角色为认证用户（authenticated），受 RLS 对认证策略约束。
• 特殊服务角色：使用服务级密钥时，角色为 service_role，可绕过 RLS。

第 5 章的行级安全策略，正是通过读取 JWT 中的用户 id 与角色来做权限判断。因此理解「JWT 里有什么」，就理解了「RLS 能基于什么做判断」。

令牌的安全存储

令牌等同于登录态，其存储位置直接影响安全：

• Web 应用：需防范跨站脚本（XSS）窃取令牌，通常由认证库在妥善处理的前提下存储。
• 移动端：应使用系统的安全存储（如钥匙串、加密存储），避免明文保存。
• 绝不要把令牌写入会被公开访问的地方（如 URL 参数、公开仓库）。

登出与会话撤销

登出不仅是「前端清除令牌」，正规做法是通知 Auth 服务撤销会话，使刷新令牌失效。这样即使令牌曾被泄露，也无法继续续期。Supabase 提供登出接口完成这一动作。

此外，对于可疑活动，可主动撤销用户的所有会话，强制其重新登录。

常见问题与排查

• 「明明登录了却访问被拒」：通常是访问令牌已过期且刷新失败，检查刷新令牌是否已过期或被撤销。
• 「令牌解析不出用户」：检查请求是否正确携带了令牌、令牌是否完整、是否被中间件误改。
• 「权限不生效」：JWT 中的角色与用户 id 决定 RLS 判断，确认令牌载荷是否如预期。

小结

JWT 是自包含、签名的访问令牌，配合刷新令牌实现「短期安全 + 长期会话」的平衡。令牌载荷中的用户 id 与角色，是第 5 章 RLS 做权限判断的依据。理解令牌的生命周期与安全存储，你就能驾驭整套认证状态。下一节进入用户管理与多因素认证，把安全再加固一层。