Skip to main contentSkip to navigation
返回博客
教程

JWT 集成教程:为您的应用添加令牌身份验证

分步教程:邮箱/密码应用中 JWT 的完整生命周期——注册、登录、令牌存储、服务端验证、双重验证与退出,并介绍如何用 jwt.io 调试令牌。

更新于
6 分钟阅读

如果你搜索 JWT 如何用于邮箱和密码认证,会发现大家一再提出同样的问题:把凭据放进令牌安全吗?还需要 HTTPS 吗?这个令牌应该由谁来读取?过期了会怎样?答案都很简短,但把它们真正弄明白,几乎就是全部的工作。

本教程使用 AuthFlow™ REST API,带你走完邮箱/密码应用中 JSON Web Token 的完整生命周期,从首次注册到退出登录。令牌格式本身定义在 RFC 7519 中,但跟着本教程操作并不需要阅读它。

JWT 是什么,又不是什么

JWT 是认证的结果,而不是认证的替代品。用户用邮箱和密码证明一次自己的身份,服务器随后返回一个已签名的令牌,表示「此人已通过认证」,之后的每个请求都携带这个令牌而不是密码。这正是 JWT 在无状态和分布式系统中很有用的原因:任何持有正确密钥的服务都可以验证令牌,而无需再次查询数据库。

JWT 由三部分组成:头部(令牌类型和签名算法)、包含用户声明的载荷,以及签名。签名用来证明令牌未被篡改,但不会隐藏任何内容。载荷只是经过 base64 编码,任何拿到令牌的人都可以读取。请把 JWT 当作「可防篡改」而不是「保密」的东西。

切勿把密码放进令牌

初学者经常问:能不能把用户的凭据存进 JWT?一般来说没有必要:令牌本身就是登录产生的短期凭据。如果需要识别用户,就在 sub 声明中放入标识符,若后端需要,再加上角色或访问级别。不要放入密码、密钥,以及任何你不希望在浏览器中被看到的内容。

HTTPS 是另一回事,所有通信都应该使用它。它保护客户端与服务器之间的流量,而 JWT 签名保护的是令牌的完整性。两者不能互相替代。

第 1 步:把 API 密钥留在服务器上

每次 AuthFlow 调用都是代表你的组织、使用所有者控制台中的 API 密钥发出的。该密钥必须保存在你可控的基础设施上,例如 AUTHFLOW_API_KEY 这样的服务器端环境变量。切勿把它放进浏览器 JavaScript。最简单安全的设计是搭建一个小型后端(或使用我们发布的 ExpressJS 代理),前端与它通信,再由它代为调用 /auth。

第 2 步:注册与登录

在注册或登录之前,你的后端要针对用户的邮箱,从 /auth/fooBar 请求一个短期的防滥用令牌。它会在 45 秒后过期,所以请在下一次调用之前立即获取,且不要重复使用。然后调用 /auth/signUp,传入 foobar 值、你的 api_key、email、符合复杂度规则的 password(8 到 32 个字符,包含大写字母、小写字母、数字和特殊字符)、fullname,并将 disclaimed 设为 true。注册成功会立即返回会话令牌,而邮箱和角色重复则会返回 409。

登录的方式相同,调用 /auth/login。成功后你会收到会话令牌:一个使用 RS512 签名的 JWT。RS512 使用密钥对,因此令牌由你永远看不到的私钥签名,并且无需共享任何密钥即可验证。

第 3 步:妥善存放令牌

后端拿到令牌后,需要决定把它放在哪里。推荐使用 HTTP-only Cookie,因为页面脚本无法读取它,这能减轻跨站脚本漏洞造成的损害。无论选择哪种方式,都要保存会话令牌而不是临时令牌,并确保它绝不会被写入日志。

第 4 步:在每个受保护的路由上验证

在后端处理受保护的请求之前,先检查令牌。使用 sessionToken 和用户的 email 调用 /auth/validate;有效的令牌会成功,无效或已过期的令牌会返回 401。需要当前用户的个人资料时,请使用 /auth/me。对每个受保护的请求都在服务器上执行这一步非常重要,因为一个从不验证的已签名令牌起不到任何保护作用。

过期是设计的一部分。令牌过期后,用户需要重新登录,而不是由你的应用悄悄地为其续期。请确保你的应用能妥善处理这个 401,把用户送回登录页。

第 5 步:处理双重身份验证

如果用户启用了 2FA,/auth/login 不会返回会话令牌,而是返回 requires2FA 和 tempToken。随后你的应用要求提供第二重验证,并通过某个 /auth/2fa 验证端点(TOTP 验证码、备用码或邮件 OTP)来换取结果。只有这次交换才会产生真正的会话令牌,所以请确保保存的是它,而绝不是 tempToken。

使用 jwt.io 调试令牌

出现问题时,想看清令牌里到底有什么,最快的办法是使用 jwt.io。把令牌粘贴到它的调试器中,就会解码出头部和载荷,你可以检查算法、sub 声明和过期时间。这通常足以发现令牌已过期、用户不对,或者误存了 tempToken。

基于以上所有内容,有一点需要提醒:令牌就是凭据。请将生产环境中有效的令牌视为敏感信息,调试时优先使用测试账号,并避免把真实令牌粘贴到任何你不信任的工具中。解码令牌不等于验证令牌。验证仍然要在你的服务器上通过 /auth/validate 完成。

第 6 步:退出登录

要结束会话,请使用 sessionToken 和 email 调用 /auth/logout,然后从你存放令牌的地方将其删除。修改密码的方式类似,通过 /auth/changePassword 完成。沿途记录认证事件,在出问题时能为你提供有用的线索。

JWT 集成检查清单

  • API 密钥只存在于服务器端配置中,绝不出现在浏览器代码里。
  • 每次注册和登录之前,都先重新调用一次 /auth/fooBar。
  • 令牌载荷中不放任何密码或密钥;用 sub 和角色来识别用户。
  • 会话令牌保存在 HTTP-only Cookie 或其他由服务器控制的存储中。
  • 每个受保护的路由在执行任何操作之前,都先通过 /auth/validate 验证令牌。
  • 令牌过期或无效(401)时,将用户送回登录页。
  • 2FA 流程中保存的是最终的会话令牌,而不是 tempToken。
  • 所有通信都使用 HTTPS,且令牌绝不写入日志。

这就是完整的闭环:认证一次,携带已签名的令牌,在服务器上验证,并让它自然过期。请阅读入门指南了解完整的端点参考,或者对比其他平台的做法。当令牌看起来不对劲时,jwt.io 会告诉你里面有什么。

JWT 集成JWT 邮箱密码身份验证基于令牌的身份验证jwt.io 调试器RS512 JWT