OAuth2.0 这个词，做过第三方登录对接的同学应该都不陌生。但真正动手从零写一套客户端和服务端，和调几个现成 SDK 完全是两码事。我见过太多项目，接入阶段照着文档抄一遍能跑通，一旦遇到令牌过期、回调地址不一致、授权码被重复使用这些情况，就开始抓瞎。问题的根源往往不在代码写错，而在于对 OAuth2.0 那套授权流程的每个环节到底在交换什么、为什么这么设计，缺乏一个完整的认知。
这篇内容我打算把 OAuth2.0 的客户端和服务端用 Java 各实现一遍，不是调库，而是把授权码模式这条主线上的每个角色、每次请求、每个参数都摊开讲清楚。适合两类人看：一类是正在做第三方登录对接、想搞明白底层到底发生了什么的开发者；另一类是想给自己系统加一套授权体系、需要理解服务端该怎么设计的同学。哪怕你之前只停留在“知道有授权码模式”这个层面，跟着走一遍也能把整条链路串起来。
我会用授权码模式作为主线，因为它是实际项目里用得最多、也最能体现 OAuth2.0 设计思想的一种。整篇内容围绕四个角色展开：资源所有者、客户端、授权服务器、资源服务器。客户端和服务端我都会给出可运行的 Java 实现思路，重点放在参数校验、令牌管理、安全边界这些真正容易出问题的地方，而不是贴一堆 CRUD 代码。
1. 先把四个角色和授权码流程的账算清楚
在动手写代码之前，必须先把 OAuth2.0 里四个角色各自负责什么、彼此之间怎么交互理清楚。很多人写代码写到一半卡住，就是因为脑子里角色是混的。我习惯把这套流程类比成“去银行办业务”：你是资源所有者，手里有存款（受保护资源）；客户端是帮你跑腿的中介；授权服务器是银行柜台，负责核实你的身份并发放凭证；资源服务器是金库，只认凭证不认人。
1.1 授权码模式到底在防什么
授权码模式的核心价值，在于它让客户端的后端参与到了令牌交换环节，从而避免了访问令牌直接暴露在前端浏览器里。整个流程分两步走：第一步，客户端把用户引导到授权服务器，用户登录并同意授权后，授权服务器通过浏览器重定向把授权码带回客户端；第二步，客户端后端拿着这个授权码，通过后端通道直接向授权服务器换取访问令牌。
这里有个关键设计意图：授权码是经由浏览器前端传递的，理论上可能被截获，所以它被设计成一次性且短时效的。即便被截获，攻击者没有客户端的密钥（client_secret），也换不出令牌。而令牌交换走的是后端直连，不经过浏览器，安全性就有了保障。理解这一点，后面写服务端校验逻辑时，你就知道为什么授权码必须用完即焚、为什么 client_secret 绝不能出现在前端。
1.2 一次完整授权涉及的四次请求
把流程拆细，一次完整的授权码模式交互包含四次关键请求，我用表格列出来，方便对照：
| 步骤 | 发起方 | 目标 | 核心参数 | 返回 |
|---|---|---|---|---|
| 1 | 客户端 | 授权服务器 | client_id、redirect_uri、response_type=code、scope、state | 授权码 code |
| 2 | 客户端后端 | 授权服务器 | grant_type=authorization_code、code、redirect_uri、client_id、client_secret | access_token、refresh_token |
| 3 | 客户端 | 资源服务器 | Authorization: Bearer access_token | 受保护资源 |
| 4 | 客户端后端 | 授权服务器 | grant_type=refresh_token、refresh_token、client_id、client_secret | 新的 access_token |
这四步里，第 1 步和第 2 步的redirect_uri必须完全一致，这是服务端校验的重点，也是实际对接中最常见的报错来源。第 3 步的 Bearer 令牌放在请求头里，而不是 URL 参数里，这是为了避免令牌被日志、代理记录下来。第 4 步的刷新令牌机制，是为了让访问令牌可以设置较短的有效期，降低泄露风险。
1.3 state 参数不是可选项
很多示例代码里state参数随手填个固定值甚至省略，这是很危险的做法。state的作用是防 CSRF 攻击：客户端在发起授权请求时生成一个随机值，存到用户会话里，授权服务器原样带回，客户端比对一致才继续。如果没有它，攻击者可以构造一个带有自己授权码的回调链接诱导用户点击，从而把用户的账号和自己的第三方账号绑定，这就是典型的授权码注入攻击。
我在实现里会把state生成一个 UUID，存进服务端 session 或者分布式缓存，回调时严格比对，不一致直接拒绝。这个细节看起来小，但它是区分“能跑”和“能上线”的分水岭。
2. 授权服务器：令牌签发的中枢该怎么搭
授权服务器是整个体系的核心，它要负责三件事：验证用户身份、管理客户端注册信息、签发和校验令牌。我用 Spring Boot 搭一个最小可用的授权服务器，重点讲清楚每个接口的校验逻辑，而不是堆砌框架配置。
2.1 客户端注册信息的内存模型
先定义一个客户端注册的数据结构。真实场景下这些信息存在数据库里，但为了讲清楚字段含义，我用一个内存 Map 模拟：
public class RegisteredClient { private String clientId; private String clientSecret; // 加密存储，比对时用哈希 private Set<String> redirectUris; // 允许的回调地址白名单 private Set<String> scopes; // 允许申请的权限范围 private int accessTokenTtl; // 访问令牌有效期（秒） private int refreshTokenTtl; // 刷新令牌有效期（秒） }这里有几个设计要点值得说。redirectUris做成集合而不是单个字符串，是因为一个客户端可能配置多个回调地址（比如测试环境和生产环境各一个），但校验时必须是精确匹配，绝不能用前缀匹配或者包含匹配，否则就给了攻击者构造恶意回调地址的空间。clientSecret存储时要做哈希，比对时用哈希值比对，避免数据库泄露导致密钥直接暴露。scopes是权限范围，客户端申请时只能申请自己注册过的范围，服务端要校验申请的 scope 是不是注册信息的子集。
2.2 授权端点：校验通过才发码
授权端点接收的是浏览器重定向过来的 GET 请求，参数包括response_type、client_id、redirect_uri、scope、state。校验顺序我总结成一条链路，任何一环失败都要按规范返回错误，而不是抛个 500 了事：
- 校验
client_id是否存在，不存在直接拒绝； - 校验
redirect_uri是否在该客户端的白名单里，精确匹配； - 校验
response_type是否为code，其他类型不支持； - 校验申请的
scope是否为注册范围的子集； - 校验用户是否已登录且同意授权（这一步通常跳登录页和授权确认页）。
全部通过后，生成授权码。授权码我建议用高熵随机串，比如SecureRandom生成 32 字节再 Base64 编码，同时把它和client_id、redirect_uri、scope、过期时间、是否已使用这些信息一起存起来。授权码有效期设短一点，60 到 300 秒足够，因为用户同意授权后浏览器会立刻跳转回来。
String code = generateSecureCode(); authCodeStore.put(code, new AuthCode( clientId, redirectUri, scope, Instant.now().plusSeconds(120), false ));注意：授权码存储一定要带“是否已使用”标记。令牌端点换令牌时，先检查这个标记，已使用的授权码直接拒绝，并且要把该授权码关联的已签发令牌一并作废。这是防重放的关键。
2.3 令牌端点：授权码换令牌的完整校验
令牌端点接收的是客户端后端的 POST 请求，参数包括grant_type、code、redirect_uri、client_id、client_secret。这里的校验比授权端点更严格，因为涉及密钥比对：
- 先做客户端认证，可以用 HTTP Basic 头，也可以把
client_id和client_secret放表单里，两种方式选一种统一即可； - 校验
grant_type是否为authorization_code； - 取出授权码记录，检查是否存在、是否过期、是否已使用；
- 校验授权码记录里的
client_id和redirect_uri与本次请求是否一致； - 全部通过后，把授权码标记为已使用，签发访问令牌和刷新令牌。
访问令牌我用 JWT 实现，好处是资源服务器可以本地校验签名，不用每次都回查授权服务器。JWT 的 payload 里放sub（用户标识）、client_id、scope、exp（过期时间）、jti（令牌唯一标识）。签名用 HMAC-SHA256，密钥只有授权服务器和资源服务器知道。
String accessToken = Jwts.builder() .setSubject(userId) .claim("client_id", clientId) .claim("scope", scope) .setExpiration(Date.from(Instant.now().plusSeconds(3600))) .setId(UUID.randomUUID().toString()) .signWith(hmacKey) .compact();刷新令牌则用不透明随机串，存服务端，因为它需要支持吊销，用 JWT 反而不方便。刷新令牌有效期可以设长一些，比如 30 天，但每次使用刷新令牌换新令牌时，建议做刷新令牌轮换：旧的刷新令牌作废，发一个新的。这样即便刷新令牌泄露，攻击者用一次之后真正的用户就会发现异常。
2.4 令牌内省与吊销接口
资源服务器如果不想自己解析 JWT，或者令牌是不透明串，就需要一个内省端点。内省端点接收令牌，返回它是否有效、对应的用户、scope、过期时间。这个端点本身要受保护，只有注册过的资源服务器才能调用。
吊销端点用于用户主动登出或者管理员封禁场景，接收令牌并把它加入黑名单。JWT 本身无法撤销，所以要么维护一个黑名单存到过期为止，要么把令牌有效期设短、靠刷新令牌控制。我一般选择后者配合短有效期，黑名单只作为应急手段。
3. 客户端：把授权码流程串成可运行的代码
客户端这边分两块：一块是引导用户跳转授权、处理回调的前端逻辑，另一块是后端换令牌、调资源的逻辑。我用一个简单的 Servlet 或者 Spring MVC 控制器来演示，重点讲清楚会话状态怎么管、令牌怎么存。
3.1 发起授权请求时的参数拼装
用户点击“用某账号登录”时，客户端后端生成state并存入会话，然后拼装授权地址重定向：
String state = UUID.randomUUID().toString(); session.setAttribute("oauth_state", state); String authUrl = authorizationEndpoint + "?response_type=code" + "&client_id=" + URLEncoder.encode(clientId, "UTF-8") + "&redirect_uri=" + URLEncoder.encode(redirectUri, "UTF-8") + "&scope=" + URLEncoder.encode("read profile", "UTF-8") + "&state=" + state; response.sendRedirect(authUrl);这里所有参数都要 URL 编码，尤其是redirect_uri和scope，里面可能带空格和特殊字符。state存会话时最好加个前缀避免和其他业务键冲突。授权地址的域名必须是授权服务器注册过的，不能动态拼接用户输入，否则就是开放重定向漏洞。
3.2 回调处理：先验 state 再换令牌
回调端点收到code和state两个参数。第一步永远是校验state：
String expectedState = (String) session.getAttribute("oauth_state"); if (expectedState == null || !expectedState.equals(state)) { // 拒绝，可能是 CSRF 攻击 return; } session.removeAttribute("oauth_state"); // 用完即删校验通过后，用code去换令牌。这一步是后端到后端的 POST 请求，client_secret放在请求体或 Basic 头里，绝不能出现在前端。换到令牌后，把access_token和refresh_token存到服务端会话或者加密的 Cookie 里，不要明文塞进前端 localStorage，那是 XSS 攻击的重灾区。
HttpResponse<String> tokenResp = httpClient.send( HttpRequest.newBuilder() .uri(URI.create(tokenEndpoint)) .header("Content-Type", "application/x-www-form-urlencoded") .POST(HttpRequest.BodyPublishers.ofString( "grant_type=authorization_code" + "&code=" + code + "&redirect_uri=" + URLEncoder.encode(redirectUri, "UTF-8") + "&client_id=" + clientId + "&client_secret=" + clientSecret)) .build(), HttpResponse.BodyHandlers.ofString());拿到响应后要检查 HTTP 状态码和响应体里的error字段，OAuth2.0 的错误响应格式是固定的，比如invalid_grant表示授权码无效或过期，invalid_client表示客户端认证失败。把这些错误码映射成用户能看懂的提示，比直接抛异常友好得多。
3.3 带令牌访问资源与自动刷新
访问资源服务器时，把令牌放在Authorization: Bearer头里：
HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(resourceUrl)) .header("Authorization", "Bearer " + accessToken) .GET() .build();如果资源服务器返回 401，说明令牌过期或无效，这时候用刷新令牌换新的访问令牌，然后重试一次。刷新逻辑要加锁或者用原子操作，避免并发请求同时触发多次刷新导致刷新令牌被轮换掉。我一般用一个带过期时间的本地缓存存令牌，快过期时提前刷新，而不是等到 401 才被动处理，这样用户体验更平滑。
4. 资源服务器：令牌校验的边界与性能取舍
资源服务器不负责发令牌，只负责验令牌。它的实现相对简单，但校验的严格程度直接决定了整个体系的安全底线。
4.1 JWT 本地校验的完整步骤
如果访问令牌是 JWT，资源服务器本地校验分四步：解析令牌、验证签名、检查过期时间、检查签发者。签名验证用和授权服务器共享的密钥，验证失败直接拒绝。过期时间检查要注意时钟偏移，一般允许几十秒的误差。
Claims claims = Jwts.parserBuilder() .setSigningKey(hmacKey) .build() .parseClaimsJws(token) .getBody(); if (claims.getExpiration().before(new Date())) { // 已过期 }校验通过后，从claims里取出sub和scope，做权限判断。比如某个接口要求write权限，就检查scope里是否包含它。这里要注意，scope 的比对要按空格拆分后逐个匹配，不能用字符串包含判断，否则read会误匹配readwrite。
4.2 不透明令牌的内省调用与缓存
如果令牌不是 JWT，资源服务器就得调授权服务器的内省端点。每次请求都调一次内省，性能开销不小，所以要在资源服务器本地做缓存，缓存键是令牌的哈希值，缓存时间取令牌剩余有效期和固定上限的较小值。缓存里只存校验结果和必要的用户信息，不存原始令牌。
内省调用本身也要做超时和降级处理。授权服务器短暂不可用时，如果缓存里还有有效的校验结果，可以继续放行；缓存也没有，就返回 503 而不是 401，避免把服务故障误判成用户未授权。
4.3 令牌泄露的应急处理
万一发现令牌泄露，处理手段有三个层次：第一，如果令牌是 JWT 且有效期短，等它自然过期；第二，把令牌的jti加入资源服务器的黑名单，校验时额外查一次黑名单；第三，通过授权服务器吊销关联的刷新令牌，让攻击者无法续期。实际项目里我建议把访问令牌有效期控制在 1 小时以内，刷新令牌做轮换，这样即便泄露，影响窗口也可控。
5. 那些文档里不写、上线才暴露的坑
前面讲的都是“应该怎么做”，这一节讲“实际做的时候会在哪里翻车”。这些经验基本都是从对接和自建过程中踩出来的，文档里通常不会提。
5.1 redirect_uri 的精确匹配陷阱
最常见的报错就是回调地址不匹配。表现是授权服务器返回redirect_uri_mismatch，但你把两个地址复制出来逐字符比对，看起来一模一样。原因通常有三类：一是末尾斜杠，https://a.com/callback和https://a.com/callback/在服务端看来是两个地址；二是大小写，域名部分不区分大小写，但路径部分区分；三是 URL 编码差异，redirect_uri在授权请求里编码了一次，在令牌请求里又编码了一次，服务端解码次数不一致就会对不上。
我的处理办法是：注册时把回调地址规范化（统一去掉末尾斜杠、统一小写域名部分），校验时对两边都做一次解码再比对。另外，令牌请求里的redirect_uri必须和授权请求里的完全一致，这是规范要求，不能省略也不能改。
5.2 授权码重复使用导致的令牌作废
规范里明确要求，授权码一旦被使用过，再次使用必须拒绝，并且要把之前基于该授权码签发的令牌全部作废。我见过有实现只做了“拒绝”，没做“作废”，结果攻击者截获授权码后用了一次，合法客户端再用时被拒绝，但攻击者手里的令牌依然有效。正确的做法是在授权码记录里关联已签发的令牌标识，检测到重复使用时触发吊销。
5.3 刷新令牌轮换引发的并发问题
刷新令牌轮换是个好机制，但它和并发是天然冲突的。用户同时打开多个标签页，每个页面都检测到访问令牌过期，同时发起刷新请求，第一个请求把旧刷新令牌用掉了，后面几个请求拿着已经作废的刷新令牌去换，全部失败，用户被强制登出。
解决办法有两个方向：客户端侧做刷新请求的合并，用一个 Promise 或者锁保证同一时刻只有一个刷新在飞，其他请求等它的结果；服务端侧给旧刷新令牌一个短暂的宽限期，比如轮换后 30 秒内旧令牌仍可用，但只返回同一个新令牌。我倾向于客户端合并为主、服务端宽限为辅，两边都做更稳。
5.4 scope 校验的粒度问题
scope 校验最容易犯的错是只校验“申请的是不是注册的子集”，却没校验“这个用户有没有这个权限”。比如客户端注册了admin这个 scope，用户 A 只是普通用户，授权时却把admin也授出去了。正确的做法是在授权确认环节，根据用户实际权限过滤可授予的 scope，用户没有的权限不能出现在同意页上，令牌签发时也不能包含。
6. 从能跑到能扛：令牌体系的加固思路
一套 OAuth2.0 实现跑通 Demo 只是起点，要真正扛住生产环境的流量和攻击面，还得在几个地方加固。这部分我按优先级从高到低说。
6.1 密钥管理与签名算法选择
HMAC-SHA256 适合单体或者信任域内共享密钥的场景，但如果资源服务器是多方独立的，用非对称签名更合适，授权服务器持私钥签名，资源服务器用公钥验签，公钥可以公开分发。密钥本身要定期轮换，JWT 头部里的kid字段用来标识用的是哪把密钥，资源服务器根据kid选择对应的公钥，这样轮换时新旧密钥可以并存一段时间，平滑过渡。
密钥绝不能硬编码在代码里，也不能提交到代码仓库。用环境变量或者配置中心注入，不同环境用不同密钥。我见过把密钥写在application.yml里然后推到公开仓库的，等于把整个令牌体系拱手让人。
6.2 令牌存储位置与传输安全
客户端拿到的令牌存在哪，直接关系到 XSS 和 CSRF 的风险。浏览器端存储有三个选择：localStorage、sessionStorage、HttpOnly Cookie。localStorage 最方便但最危险，任何 XSS 都能读走；HttpOnly Cookie 能防 XSS 读取，但要配合 SameSite 属性防 CSRF。我的建议是：访问令牌放内存变量，刷新令牌放 HttpOnly + Secure + SameSite=Strict 的 Cookie，页面刷新时用刷新令牌换新的访问令牌。
传输层面，所有 OAuth2.0 相关端点必须走 HTTPS，包括授权端点、令牌端点、内省端点。授权码和令牌在明文 HTTP 下传输，等于把凭证直接广播出去。
6.3 限流与异常监控
令牌端点是被暴力攻击的重点目标，攻击者可能拿大量授权码或者刷新令牌来试探。要在令牌端点和内省端点做限流，按客户端维度限，也按 IP 维度限。同时监控异常模式：短时间内大量invalid_grant错误、同一客户端从异常地理位置发起令牌请求、授权码重复使用告警，这些都值得接入监控告警。
日志里绝对不能打印完整的令牌和授权码，最多打印前几位加哈希。我见过排查问题时把完整令牌打进日志，结果日志系统被拖库，令牌全部泄露的事故。
6.4 授权确认页的体验与安全平衡
授权确认页是用户唯一能看清“这个应用要我的什么权限”的地方，但很多实现把它做成一个默认勾选、一键同意的形式，用户根本没看。从安全角度，应该把申请的 scope 用用户能理解的语言展示出来，敏感权限单独高亮，并且默认不勾选。从体验角度，别把确认页做得太复杂，权限描述要短、要具体，比如“读取你的昵称和头像”比“访问用户基本信息”清楚得多。
我在实际项目里会把 scope 和展示文案做成映射表，服务端签发令牌时用 scope 标识，前端展示时查表换成文案，两边解耦，改文案不用动授权逻辑。
7. 一套可复用的实现骨架长什么样
讲了这么多细节，最后落到代码组织上。一套能长期维护的 OAuth2.0 实现，我倾向于按职责拆成几个模块，而不是全塞在一个类里。
7.1 服务端的模块划分
授权服务器至少拆成四块：客户端注册管理、授权码管理、令牌签发、令牌校验。客户端注册管理负责增删改查和密钥哈希；授权码管理负责生成、存储、消费、过期清理；令牌签发负责组装 JWT 和刷新令牌；令牌校验负责内省和吊销。每块之间通过接口交互，方便单独测试和替换实现。
授权码和刷新令牌的存储，单机可以用带过期时间的本地缓存，集群必须用 Redis 这类共享存储，并且要注意过期时间的设置和清理策略。授权码的过期清理可以靠存储自带的 TTL，刷新令牌的轮换和吊销则需要显式的状态管理。
7.2 客户端的配置抽象
客户端这边，把授权端点、令牌端点、client_id、client_secret、redirect_uri、scope 这些做成配置项，不同环境用不同配置。换令牌和刷新的逻辑封装成一个TokenClient类，对外只暴露getAccessToken()和refresh()两个方法，内部处理缓存、并发、重试。这样业务代码完全不用关心 OAuth2.0 的细节，只调一个方法拿令牌。
public interface TokenClient { String getAccessToken(); // 自动处理缓存和刷新 void invalidate(); // 强制失效，用于登出 }7.3 测试策略：把异常路径也覆盖到
OAuth2.0 的测试重点不在正常流程，而在异常路径。我一般会覆盖这些用例：授权码过期、授权码重复使用、redirect_uri 不匹配、client_secret 错误、scope 越权申请、state 不匹配、刷新令牌已吊销、令牌签名被篡改。每个用例都断言返回的错误码符合规范，而不是笼统的 400。
集成测试里可以用一个内存版的授权服务器和资源服务器，把整条链路跑通，再针对每个异常点单独构造请求。这样改代码时能快速发现回归，比手工点页面靠谱得多。
这套东西写下来，代码量其实不大，难的是把每个校验点的意图想明白。OAuth2.0 的规范读起来枯燥，但每一条校验要求背后基本都对应一个真实发生过的攻击场景。把规范当“安全检查清单”来读，比当“接口文档”来读收获大得多。我自己在实现时养成了一个习惯：每写一个校验分支，就在注释里写清楚它在防什么，时间长了这份注释本身就是一份安全设计文档。
