文档教程知识库【免费下载链接】developer-roadmapInteractive roadmaps, guides and other educational content to help developers grow in their careers.项目地址https://gitcode.com/GitHub_Trending/de/developer-roadmap点击查看免费下载JSON Web TokenJWT是一种紧凑、URL 安全的令牌格式用于在 API 的通信双方之间安全地传递声明claims。它凭借轻量、无状态、可扩展的特性成为现代 RESTful API 中认证与授权的主流方案之一。本文以本仓库 API 设计路线图 中关于 JWT 的专题为骨架深入剖析其结构、签名机制、在 API 设计中的定位、实际使用流程与安全最佳实践帮助你理解为什么 JWT 能在无服务器会话存储的情况下完成身份验证与信息交换并掌握在 API 网关、微服务、OAuth 2.0 / OIDC 等场景中的落地要点。JWT 是什么定义与设计动机在 API 设计领域JWT 是一种广受欢迎且安全的信息传递方式。它本质上是一个自包含self-contained的令牌所有需要传递的声明如用户身份、角色、权限、过期时间都被编码进令牌本身而不是保存在服务器端。JWT 的设计动机可以概括为三点紧凑CompactJWT 的最终形态是一段较短的字符串可以轻松放进 HTTP Header如Authorization: Bearer token、URL 查询参数或 Cookie 中不会显著增加请求体积URL 安全URL-safeJWT 使用 Base64URL 编码不会产生、/、等在 URL 传输中易出错的字符可以直接在地址栏、查询参数中安全传递可验证Verifiable令牌携带数字签名digital signature接收方无需访问认证中心即可验证令牌的完整性与真实性确保 API 端点能够以安全可靠的方式处理请求。正是这些特性使 JWT 成为比服务器端会话 Session ID更易水平扩展的认证方案令牌可以在任意服务实例上被独立校验服务端无需共享会话存储。JWT 的结构解剖一个 JWT 由三部分组成彼此用.分隔形如Header.Payload.Signature例如eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5cHeader头部Header 是一个 JSON 对象通常包含令牌的类型与签名算法例如{ alg: HS256, typ: JWT }typ固定为JWT声明这是一个 JSON Web Tokenalg声明签名/加密算法常见取值包括HS256HMAC SHA-256对称密钥、RS256RSA SHA-256非对称密钥、ES256ECDSA SHA-256等。Payload负载Payload 承载实际要传递的声明可以划分为三类注册声明Registered claims由规范定义的、具有约定语义的字段如subSubject令牌主体通常是用户 IDissIssuer签发者audAudience受众即令牌面向的 API 服务expExpiration Time过期时间Unix 时间戳iatIssued At签发时间nbfNot Before在此时间之前令牌无效。公共声明Public claims由使用方自定义但建议在 IANA JSON Web Token Claims 注册表中登记以避免冲突的字段私有声明Private claims通信双方私下约定的自定义字段如role、tenant_id。{ sub: 1234567890, name: John Doe, role: admin, iat: 1516239022, exp: 1616239022 }注意Header 与 Payload 仅做 Base64URL 编码并未加密任何人解码即可读取内容。因此严禁在 JWT 中存放密码、身份证号等敏感数据JWT 只适合承载可公开或非敏感的声明信息。Signature签名签名由发送方使用密钥对编码后的 Header . 编码后的 Payload进行签名运算得到具体流程取决于算法对称算法如HS256HMACSHA256(base64url(header) . base64url(payload), secret)非对称算法如RS256使用私钥签名接收方用公钥验证。签名的意义在于任何对 Header 或 Payload 的篡改都会导致验签失败从而保证令牌在传输过程中的完整性与真实性。签名算法选型HS256 与 RS256算法选择直接决定密钥管理方式与信任模型是 API 设计中的关键决策维度HS256HMAC SHA-256RS256RSA SHA-256密钥类型对称签发与验证使用同一把密钥非对称签发用私钥验证用公钥密钥分发密钥必须保密只能与可信后端共享公钥可公开任意服务均可独立验签适用场景单一服务、内部系统、签发与验证同属一方认证中心签发、多个 API 服务独立验证微服务、API 网关性能运算更快运算相对较慢在微服务或认证中心统一签发、各 API 服务独立验证的架构中RS256是更稳妥的选择——因为任意服务只需持有公钥即可验签即使某个服务被攻破也不会泄露签发私钥。相关密钥生成与轮换的实践可参考本仓库的 Key Generation Rotation 专题。JWT 在 API 设计中的定位与基于会话Session的认证对比JWT 属于无状态令牌认证。与其形成对照的是本仓库中同样重点介绍的 Session Based Authentication会话方案在用户登录后由服务器创建会话并关联一个 Session ID客户端以 Cookie 保存后续请求由服务器校验 Session ID登出后销毁会话——状态保存在服务器端JWT 方案则把全部状态内聚于令牌本身服务器无需持久化存储令牌即可完成校验。正如 Token Based Auth 中所强调的令牌可以由服务器创建和校验而无需持久化存储这使应用更易于水平扩展——这正是 JWT 在现代 RESTful API 中被广泛采用的核心原因。会话方案在可主动撤销、即时登出方面更有优势而 JWT 的优势在于无状态、跨服务共享、天然适配分布式与微服务架构。两者并无绝对优劣应根据安全优先级与扩展性需求权衡。在 OAuth 2.0 与 OIDC 中的角色JWT 在 OAuth 2.0 与 OpenID Connect 生态中扮演核心载体在 OAuth 2.0 授权框架中授权服务器颁发的**访问令牌Access Token**常以 JWT 形式存在客户端凭它访问受保护的 API 端点在 OIDCOpenID Connect 中ID Token 本身就是一个已签名的 JWT携带关于已认证用户姓名、邮箱、用户 ID 等的声明。OIDC 正是使用 Google / GitHub / Apple 账号登录流程背后的标准当你的 API 需要验证用户是谁而非仅有何权限时OIDC 是正确选择。换言之掌握 JWT 的结构与验签机制是理解 OAuth 2.0 授权流程、OIDC 身份层乃至现代 API 安全体系的前提。在 API 中的实际使用流程一个典型的 JWT 认证流程如下认证客户端向认证端点提交用户名/密码等凭证签发认证服务器验证凭证后构造 Header 与 Payload使用密钥签发 JWT 并返回给客户端携带客户端在后续每个 API 请求的Authorization头中携带令牌Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...验证API 服务解析令牌使用密钥对称或公钥非对称验签并校验exp、aud、iss等声明验证通过后从 Payload 中提取用户身份与权限决定是否放行请求过期与刷新令牌过期exp到达后客户端通过刷新令牌Refresh Token重新获取新的访问令牌避免频繁重新登录。在分布式场景中这一步通常由API 网关统一完成网关验签通过后把用户身份注入下游请求上下文各业务服务无需重复验签逻辑从而简化 微服务架构 下的安全实现。安全最佳实践结合本仓库 API Security 与 Key Generation Rotation 两个专题的指导方向JWT 落地时应遵循以下实践固定算法、拒绝算法混淆攻击验签时必须显式指定允许的算法如仅允许RS256绝不能直接采用令牌 Header 中声明的alg值否则攻击者可伪造alg: none或切换到弱算法务必校验关键声明验签之外还要校验exp是否过期、nbf是否生效、aud是否面向本 API、iss是否来自可信签发方密钥管理签名密钥应足够随机且长度达标以抵抗暴力破解密钥需要定期轮换按计划或在疑似泄露后轮换时确保新旧密钥平滑过渡、不造成服务中断这是 Key Generation Rotation 强调的核心要点内容最小化只放入必要的声明绝不放入密码、密钥等敏感信息JWT 可被任何人解码传输安全JWT 应仅在 HTTPS 之上传输避免令牌在网络中被窃听若存放在 Cookie 中应设置HttpOnly、Secure、SameSite等属性令牌生命周期访问令牌应设置较短的exp配合刷新令牌机制控制风险窗口。学习路径与延伸阅读JWT 只是 API 认证方法谱系中的一员。在 API 设计路线图 的完整知识体系中推荐按以下路径继续深入学习Authentication Methods概览 Basic、API Key、OAuth、JWT 等各类认证方法的适用场景Token Based Auth理解无状态令牌认证在 RESTful API 中的定位Session Based Authentication与 JWT 方案对比掌握各自取舍OAuth 2.0 与 OIDC理解 JWT 作为访问令牌与 ID Token 的实战场景Key Generation Rotation签名密钥的生成、分发与轮换规范API Security从整体安全视角审视认证、授权与威胁防护。通过将 JWT 的结构、签名、验证、密钥管理四个层次逐一吃透再结合 OAuth 2.0 / OIDC 的授权与身份流你便能在实际的 API 设计工作中正确选型与安全落地 JWT而非仅仅会用一个库。赞分享文档教程知识库【免费下载链接】developer-roadmapInteractive roadmaps, guides and other educational content to help developers grow in their careers.项目地址https://gitcode.com/GitHub_Trending/de/developer-roadmap点击查看免费下载相关推荐LongCat-Flash-Thinking-FP8模型配置详解configuration_longcat_flash.py参数解析LongCat Flash Thinking FP8模型配置详解configuration_longcat_flash.py参数解析 LongCat Flas探索 golang-jwt/jwt: Go 语言中的 JSON Web Token 实现探索 golang jwt/jwt : Go 语言中的 JSON Web Token 实现 在现代Web开发中JSON Web TokenJWT已经成为一认证鉴权后端node-jwt-simple: 简单易用的JSON Web Token库node jwt simple: 简单易用的JSON Web Token库 该项目是一个简单的Node.js模块可以轻松实现JSON Web TokensJ密码学创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考