单点登录这个词做过中后台系统的人应该都不陌生。但凡公司内部系统超过三个账号体系就会变成一团乱麻人事一套、财务一套、工单一套、监控一套员工每天上班第一件事就是回忆自己昨天把密码改成了什么。而 OAuth2 方式的单点登录就是目前业界最主流、也最经得起考验的解法之一。它解决的核心问题很朴素——让用户只登录一次就能访问所有相互信任的应用系统同时把认证这件事从各个业务系统里彻底剥离出来交给一个专门的授权服务器统一管理。这篇文章适合谁看如果你正在做多系统的统一认证改造或者被“用户信息同步”“token 校验”“跨域登录态”这些问题折磨过那这篇内容基本能覆盖你 80% 的疑问。我会从整体设计思路讲到具体的授权码流程、token 设计、网关校验、踩坑排查尽量把每一步背后的“为什么”都讲清楚而不是只丢一段配置让你抄。需要说明的是OAuth2 本身是授权框架不是纯粹的认证协议用它做单点登录时有一些约定俗成的扩展做法这些细节我会在对应位置点明。1. 单点登录整体设计与 OAuth2 选型思路1.1 为什么是 OAuth2而不是自己造轮子先说一个很多人踩过的坑早期不少团队做单点登录第一反应是自己写一套“共享 session”或者“加密 cookie 跨域传递”的方案。我见过一个项目把用户 ID 和时间戳拼起来做个 MD5 当凭证在各个子系统之间用 URL 参数传递。上线三个月就出了安全事故——凭证被截获后可以无限期重放。这类自研方案的通病是只考虑了功能没考虑凭证的生命周期、撤销、刷新和防重放。OAuth2 的价值恰恰在于它把这些安全细节标准化了。它定义了一套完整的角色模型和授权流程资源所有者就是用户本人。客户端想要访问用户资源的应用比如工单系统、报表系统。授权服务器统一发放凭证的地方也就是单点登录的核心。资源服务器存放用户数据、需要校验凭证才能访问的服务。用 OAuth2 做单点登录本质上是把“认证”这一步委托给授权服务器业务系统只负责拿着授权服务器发的 token 去换用户身份。这样做的好处是职责单一业务系统不用再存密码、不用再管密码策略、不用再处理找回密码这些全部收敛到授权服务器一处。1.2 授权码模式为什么是首选OAuth2 有四种授权模式授权码、简化、密码、客户端凭证。做单点登录授权码模式Authorization Code几乎是唯一正确选择原因有三点。第一token 不经过浏览器前端。授权码模式里浏览器只拿到一个一次性的 code真正的 access_token 是后端服务器之间通过安全通道交换的。这样即使前端被 XSS 攻击攻击者也拿不到 token。第二支持 PKCE 扩展。现在的授权码模式基本都会配合 PKCEProof Key for Code Exchange防止授权码被拦截后冒用。虽然 PKCE 最初是为移动端设计的但 Web 端加上它也没坏处。第三可以配合 refresh_token 实现长期登录态。用户不用每次 token 过期都重新走一遍登录流程。密码模式看起来更简单直接拿用户名密码换 token但它要求业务系统接触用户密码这恰恰违背了单点登录“密码只在一处”的初衷所以只适合高度信任的第一方应用不推荐用于标准单点登录。1.3 整体架构分层一个典型的 OAuth2 单点登录架构我会把它拆成四层来看层级职责典型组件接入层统一入口、路由转发网关认证层登录、发码、发 token授权服务器资源层校验 token、返回用户信息用户中心服务业务层各业务系统工单、报表、监控等这里有个关键设计决策token 的校验放在网关还是放在各业务系统。我的建议是放在网关统一做。原因很简单如果每个业务系统都自己写一遍 token 校验逻辑迟早会出现某个系统校验漏了、或者校验逻辑不一致的情况。放在网关业务系统只需要从请求头里读网关透传过来的用户信息即可代码量能减少一大半。2. 核心流程拆解与关键参数设计2.1 授权码流程的完整时序整个登录流程走下来大致是这样一条链路。我用文字把每一步说清楚因为这里每一步都有坑。用户访问业务系统 AA 发现本地没有登录态于是把用户重定向到授权服务器的授权端点带上 client_id、redirect_uri、scope、state、code_challenge 等参数。授权服务器检查用户是否已登录。没登录就展示登录页登录成功后生成一个一次性的授权码 code重定向回 A 的 redirect_uri并原样带回 state。A 的后端拿到 code用 client_id、client_secret、code、code_verifier 去授权服务器的 token 端点换取 access_token 和 refresh_token。A 拿到 token 后可以调用用户中心服务获取用户信息建立本地会话。用户再访问业务系统 BB 同样重定向到授权服务器但此时授权服务器发现用户已有登录态直接发码用户无感知完成登录。第 5 步就是“单点”的精髓所在——授权服务器上的登录态是共享的所以第二个系统不需要用户再输密码。2.2 state 参数别把它当摆设state 参数很多人随手填个固定值这是很危险的做法。state 的作用是防止 CSRF 攻击攻击者可以构造一个带有自己授权码的回调链接诱导用户点击如果用户点击后业务系统直接用这个 code 换 token就会把攻击者的账号登录到用户浏览器上。正确做法是每次发起授权请求时生成一个随机 state存到用户会话里回调时比对。不一致就直接拒绝。这个随机值建议用加密安全的随机数生成器长度至少 16 字节。2.3 PKCE 的 code_challenge 计算PKCE 的核心是客户端生成一个随机的 code_verifier把它做 SHA256 哈希再 base64url 编码得到 code_challenge授权请求时带上 code_challenge换 token 时带上原始 code_verifier。授权服务器比对哈希值一致才发 token。// 生成 code_verifier 和 code_challenge 的示例 const crypto require(crypto); function base64UrlEncode(buffer) { return buffer.toString(base64) .replace(/\/g, -) .replace(/\//g, _) .replace(//g, ); } const codeVerifier base64UrlEncode(crypto.randomBytes(32)); const codeChallenge base64UrlEncode( crypto.createHash(sha256).update(codeVerifier).digest() );注意code_verifier 必须存在服务端会话里不能放在前端。如果放在前端PKCE 就失去意义了。2.4 token 的格式选择JWT 还是随机串这是设计阶段必须拍板的问题。两种方案各有取舍对比项JWT随机串 服务端存储校验方式本地验签无需查库必须查存储撤销能力弱需配合黑名单强删除即失效携带信息可内嵌用户信息需额外查询体积较大较小我的实践经验是access_token 用 JWTrefresh_token 用随机串。access_token 生命周期短一般 15 分钟到 2 小时用 JWT 可以让网关本地验签性能好refresh_token 生命周期长必须能撤销所以用随机串存服务端用户登出或改密码时直接删掉。JWT 的 payload 里建议放这些字段用户 ID、客户端 ID、签发时间、过期时间、scope。不要放敏感信息因为 JWT 只是签名不是加密payload 是 base64 编码的任何人都能解开看。3. 实操落地从授权服务器到网关校验3.1 授权服务器的核心端点实现授权服务器至少要提供四个端点授权端点、token 端点、用户信息端点、撤销端点。我用一个简化的 Node.js 示例说明 token 端点的核心逻辑。// token 端点核心逻辑伪代码突出关键校验 async function tokenEndpoint(req, res) { const { grant_type, code, redirect_uri, client_id, code_verifier } req.body; if (grant_type ! authorization_code) { return res.status(400).json({ error: unsupported_grant_type }); } // 1. 校验客户端 const client await findClient(client_id); if (!client) return res.status(401).json({ error: invalid_client }); // 2. 取出授权码校验是否过期、是否已使用 const authCode await findAuthCode(code); if (!authCode || authCode.used || authCode.expiresAt Date.now()) { return res.status(400).json({ error: invalid_grant }); } // 3. 校验 redirect_uri 与授权时一致 if (authCode.redirectUri ! redirect_uri) { return res.status(400).json({ error: invalid_grant }); } // 4. 校验 PKCE const expectedChallenge base64UrlEncode( crypto.createHash(sha256).update(code_verifier).digest() ); if (expectedChallenge ! authCode.codeChallenge) { return res.status(400).json({ error: invalid_grant }); } // 5. 标记授权码已使用防止重放 await markAuthCodeUsed(code); // 6. 签发 token const accessToken signJwt({ sub: authCode.userId, client_id, scope: authCode.scope }); const refreshToken generateRandomString(48); await saveRefreshToken(refreshToken, authCode.userId, client_id); res.json({ access_token: accessToken, token_type: Bearer, expires_in: 3600, refresh_token: refreshToken }); }这里有几个细节值得强调。授权码必须一次性使用用过就标记否则攻击者拿到 code 后可以反复换 token。授权码有效期要短一般 5 分钟足够太长会增加被拦截的风险。redirect_uri 必须严格比对不能只比对域名要完整匹配否则可能被开放重定向漏洞利用。3.2 网关统一校验的实现网关校验 token 的流程我一般这样设计// 网关过滤器核心逻辑Java 伪代码 public boolean preHandle(HttpServletRequest request) { String authHeader request.getHeader(Authorization); if (authHeader null || !authHeader.startsWith(Bearer )) { return reject(missing_token); } String token authHeader.substring(7); try { Claims claims Jwts.parser() .setSigningKey(publicKey) .parseClaimsJws(token) .getBody(); // 校验过期时间 if (claims.getExpiration().before(new Date())) { return reject(token_expired); } // 把用户信息透传给下游 request.setAttribute(userId, claims.getSubject()); request.setAttribute(scope, claims.get(scope)); return true; } catch (JwtException e) { return reject(invalid_token); } }网关验签用的是公钥私钥只在授权服务器手里。这样即使网关被攻破攻击者也无法伪造 token。这是非对称加密相比对称加密的核心优势。3.3 前端登录态的处理前端这块有个常见误区把 access_token 存 localStorage。我不推荐这么做因为 localStorage 能被任意同源 JS 读取一旦有 XSS 漏洞token 直接泄露。更稳妥的做法是access_token 只存在内存里refresh_token 放在 HttpOnly Secure SameSite 的 Cookie 里。access_token 过期时前端调用刷新接口后端用 Cookie 里的 refresh_token 换新的 access_token。这样即使 XSS 也拿不到 refresh_token。提示SameSite 属性建议设为 Lax 或 Strict。如果业务涉及跨站跳转回调Lax 通常够用Strict 最安全但可能影响部分跳转场景需要实测。3.4 登出与 token 撤销单点登录的登出比登录更容易被忽视。用户在一个系统点了登出其他系统还保持着登录态这体验就很割裂。标准做法是提供一个全局登出端点用户登出时先调用授权服务器的撤销端点把 refresh_token 作废然后清除授权服务器上的登录会话最后各业务系统通过前端轮询或 WebSocket 感知到登出事件清理本地会话。如果不想做实时通知退而求其次的方案是access_token 保持短生命周期登出后最多再过 15 分钟所有系统的 token 自然过期。这个折中方案在很多中小型系统里够用了。4. 常见问题排查与避坑经验4.1 跨域与 Cookie 问题速查跨域是单点登录里最高频的坑我整理了一张速查表现象可能原因排查方向回调后 Cookie 没带上SameSite 设置过严检查 SameSite 和 Secure 组合预检请求失败未允许 Authorization 头检查 CORS 配置的 allowedHeaders登录态丢失域名不一致确认 Cookie 的 Domain 覆盖所有子域重定向循环授权服务器自身也要求登录排除授权服务器路径的拦截这里重点说下 Cookie 的 Domain。如果业务系统是 a.example.com 和 b.example.com授权服务器是 sso.example.com那 Cookie 的 Domain 要设为.example.com这样三个子域都能共享。但要注意Domain 设得越宽安全边界越大所以不要设成顶级域。4.2 token 过期引发的连锁反应我遇到过最典型的问题access_token 设了 30 分钟结果用户在填一个长表单填到 25 分钟时提交token 刚好过期请求失败用户填的内容全丢了。解决办法有两个。一是前端做无感刷新在请求拦截器里判断 token 快过期时提前用 refresh_token 换新的。二是后端做宽限期token 过期后 60 秒内仍接受给刷新留出窗口。我一般两个都用体验最顺滑。无感刷新的关键是要加锁避免并发请求同时触发多次刷新。可以用一个 Promise 缓存第一个请求发起刷新后续请求都等这个 Promise 的结果。4.3 时钟偏移导致的验签失败JWT 验签时如果授权服务器和网关的服务器时间差了哪怕几十秒就可能出现“token 刚签发就过期”或者“token 已过期却还能用”的诡异现象。处理办法是在验签时设置时钟容差clock skew一般给 60 秒。同时所有服务器必须开启 NTP 时间同步。这个坑很隐蔽因为本地测试时两台机器时间往往一致一上生产环境多台机器就暴露了。4.4 授权码被重放的排查如果发现日志里有同一个 code 被多次用于换 token基本可以确定是重放攻击或者客户端重试逻辑有问题。排查步骤先看授权码是否被正确标记为已使用再看客户端是不是在 token 请求超时后无脑重试。token 端点必须保证幂等性处理——同一个 code 第二次来直接返回错误而不是再发一次 token。如果客户端确实需要重试应该重新走一遍授权流程拿新 code。4.5 我的几条实操心得第一scope 要设计得细。不要所有客户端都给一个all权限按业务划分成user:read、order:write这种粒度。这样即使某个客户端的 token 泄露影响范围也可控。第二client_secret 要能轮换。设计时就支持一个客户端配置多个 secret轮换时新旧并存一段时间避免换 secret 导致服务中断。第三日志要脱敏。token、code、client_secret 这些绝对不能明文打进日志。我见过有团队把完整 token 打进访问日志结果日志被同步到第三方平台等于把钥匙挂在了门上。第四压测要覆盖 token 刷新场景。很多系统登录压测没问题但大量 token 同时过期时刷新接口被打爆。刷新接口的 QPS 承载能力要单独评估。5. 安全加固与扩展场景5.1 必须开启的安全措施清单把单点登录做到“能用”和做到“安全”中间差着不少工作。下面这些措施我建议一条条对照落实强制 HTTPS所有涉及 token 传输的端点必须走 HTTPS包括内网调用。redirect_uri 白名单授权服务器只接受预先注册的回调地址禁止通配符。token 绑定客户端access_token 里带上 client_id资源服务器校验时确认 token 是发给自己的。刷新令牌轮换每次用 refresh_token 换新 token 时旧的 refresh_token 立即作废发一个新的。这样即使 refresh_token 泄露攻击者用一次后真正的用户就会发现异常。登录失败限流按账号和 IP 双维度限流防止暴力破解。异常登录检测异地、新设备登录时触发二次验证。5.2 多端登录与设备管理现在的系统往往要支持 Web、移动端、桌面端同时登录。OAuth2 本身不限制一个用户能有多少个 token所以需要业务层自己控制。我的做法是每个设备一个独立的 refresh_tokenaccess_token 不区分设备。用户可以在“设备管理”页面看到所有活跃设备手动踢掉某个设备。踢设备本质上就是删掉对应的 refresh_token等 access_token 过期后该设备就自动掉线了。如果要求踢掉后立即生效就需要维护一个 access_token 黑名单网关验签后再查一次黑名单。这会牺牲一点性能但对安全要求高的场景值得。5.3 与第三方登录的整合很多系统既要支持内部账号单点登录又要支持第三方账号登录。这两套体系可以统一到同一个授权服务器下内部账号走标准的授权码流程第三方账号走各自的 OAuth 流程但最终都映射到授权服务器内部的用户 ID签发统一的 token。关键点是账号绑定。用户第一次用第三方账号登录时如果系统里已有同邮箱的内部账号要引导用户确认绑定而不是自动合并。自动合并有账号劫持风险——如果第三方平台的邮箱验证不严攻击者可能用别人的邮箱注册第三方账号然后自动接管内部账号。5.4 微服务场景下的 token 传递在微服务架构里网关校验完 token 后下游服务之间怎么传递用户身份有两种做法。一种是继续透传原始 token每个服务都自己验签。好处是无状态坏处是每个服务都要拿到公钥、都要写验签逻辑。另一种是网关把用户信息放进内部请求头比如X-User-Id、X-User-Scope下游服务直接读。好处是下游简单坏处是这些头必须由网关强制覆盖防止外部伪造。如果网关没做好头部的清洗外部请求带个X-User-Id就能冒充任意用户这是很严重的安全漏洞。我倾向于第二种但前提是网关必须无条件覆盖这些内部头并且内部服务不对外暴露。如果内部服务可能被直接访问那还是老老实实每个服务验签。6. 性能优化与监控告警6.1 验签性能优化JWT 验签是 CPU 密集型操作尤其是 RS256 这种非对称算法。在 QPS 高的网关验签可能成为瓶颈。优化手段有几个。一是缓存公钥不要每次验签都去拉 JWKS。二是用 ES256 替代 RS256椭圆曲线算法在同等安全强度下更快、密钥更短。三是热点 token 缓存验签结果同一个 token 在有效期内多次请求可以缓存“验签通过”的结果key 用 token 的哈希值。不过缓存验签结果要小心缓存时间不能超过 token 剩余有效期否则 token 撤销后缓存还在放行。6.2 关键监控指标单点登录是全局入口它挂了整个公司都用不了系统所以监控必须到位。我一般盯这几个指标指标含义告警阈值建议登录成功率成功登录 / 总登录尝试低于 95% 告警token 端点 P99 延迟换 token 的响应时间超过 500ms 告警授权码使用率已使用 code / 已发放 code异常偏低说明流程中断刷新失败率刷新失败 / 刷新请求超过 1% 告警验签失败率验签失败 / 验签请求突增说明可能被攻击登录成功率突然下降往往是授权服务器或用户中心出了问题验签失败率突增可能是有人在拿伪造 token 试探也可能是密钥轮换没同步。6.3 灰度与回滚单点登录改造涉及所有系统不可能一次性全切。我的建议是按系统灰度先切一个边缘的、影响小的系统跑一周没问题再切核心系统。灰度期间两套登录方式并存用户可以选择用新的单点登录也可以走老的本地登录。回滚方案要提前准备好。最怕的是授权服务器上线后发现严重 bug但所有系统已经切过去了回滚都来不及。所以灰度期间一定要保留老登录入口并且明确回滚的触发条件和操作步骤。密钥轮换也要灰度。新密钥发布后授权服务器用新私钥签发 token网关同时信任新旧两个公钥等所有旧 token 都过期后再移除旧公钥。这个过渡期至少要是 access_token 生命周期的一倍。7. 我踩过的几个真实坑说几个文档里不会写、但实际一定会遇到的问题。第一个坑是重定向地址的编码。redirect_uri 里如果带了查询参数比如?from/dashboard在授权请求里必须做 URL 编码否则参数会被截断。我见过因为没编码导致回调后跳转丢失、用户回到首页的情况排查了半天才发现是编码问题。第二个坑是并发刷新。前端多个请求同时发现 token 过期同时发起刷新结果第一个刷新成功后 refresh_token 轮换了后面几个用旧 refresh_token 刷新全部失败用户被踢下线。解决办法就是前面说的加锁用一个共享 Promise 保证同一时间只有一个刷新请求。第三个坑是移动端的 WebView。移动端 App 内嵌 WebView 做单点登录时Cookie 的存储和普通浏览器不一样有些 WebView 默认不持久化 Cookie导致每次打开都要重新登录。需要在 WebView 初始化时显式开启 Cookie 持久化并且处理好 App 原生登录态和 WebView 登录态的同步。第四个坑是时间同步。前面提过时钟偏移这里再强调一次因为真的太常见了。容器化部署后容器时间默认跟宿主机走如果宿主机 NTP 没配好容器时间就是错的。上线前一定要检查所有节点的时间偏差。第五个坑是日志里的 token 泄露。有一次排查问题发现某个中间件把完整的请求头打进了日志包括 Authorization。后来我们加了个日志脱敏规则所有匹配Bearer xxx的内容统一替换成Bearer ***。这个规则建议在项目初期就加上事后补很麻烦。8. 后续可扩展的方向单点登录做完只是起点后面还有不少可以深挖的地方。一是接入 OIDC。OAuth2 只解决授权不解决认证。OIDCOpenID Connect在 OAuth2 之上加了一层 ID Token标准化了“我是谁”这个问题。如果未来要对接更多第三方系统直接上 OIDC 会比纯 OAuth2 更规范。二是做细粒度授权。现在 token 里带的是 scope粒度比较粗。如果业务需要更细的权限控制可以引入 UMAUser-Managed Access或者自己设计基于资源的权限模型把权限判断下沉到资源服务器。三是无密码登录。结合 WebAuthn用户可以用指纹、人脸、硬件密钥登录彻底告别密码。这在大企业内网场景下体验提升很明显也避免了弱密码问题。四是风险自适应认证。根据登录时的设备指纹、地理位置、行为特征动态调整认证强度。低风险直接放行高风险要求二次验证。这套东西做起来复杂但对安全敏感的业务价值很大。单点登录这个事说难不难说简单也不简单。核心流程就那么几步但每一步的安全细节、边界情况、性能考量加起来能写满一整本笔记。我的建议是先把授权码流程跑通再逐步加固安全和体验不要一上来就追求大而全。真正上线后你会发现最花时间的往往不是主流程而是那些边边角角的兼容和排查。把日志打全、把监控做好、把回滚方案备好比什么都重要。 
长河君 · 2026/10/21 17:50:23 · 阅读 1.2k OAuth2单点登录实战：授权码流程、Token设计与网关校验避坑指南
单点登录这个词做过中后台系统的人应该都不陌生。但凡公司内部系统超过三个账号体系就会变成一团乱麻人事一套、财务一套、工单一套、监控一套员工每天上班第一件事就是回忆自己昨天把密码改成了什么。而 OAuth2 方式的单点登录就是目前业界最主流、也最经得起考验的解法之一。它解决的核心问题很朴素——让用户只登录一次就能访问所有相互信任的应用系统同时把认证这件事从各个业务系统里彻底剥离出来交给一个专门的授权服务器统一管理。这篇文章适合谁看如果你正在做多系统的统一认证改造或者被“用户信息同步”“token 校验”“跨域登录态”这些问题折磨过那这篇内容基本能覆盖你 80% 的疑问。我会从整体设计思路讲到具体的授权码流程、token 设计、网关校验、踩坑排查尽量把每一步背后的“为什么”都讲清楚而不是只丢一段配置让你抄。需要说明的是OAuth2 本身是授权框架不是纯粹的认证协议用它做单点登录时有一些约定俗成的扩展做法这些细节我会在对应位置点明。1. 单点登录整体设计与 OAuth2 选型思路1.1 为什么是 OAuth2而不是自己造轮子先说一个很多人踩过的坑早期不少团队做单点登录第一反应是自己写一套“共享 session”或者“加密 cookie 跨域传递”的方案。我见过一个项目把用户 ID 和时间戳拼起来做个 MD5 当凭证在各个子系统之间用 URL 参数传递。上线三个月就出了安全事故——凭证被截获后可以无限期重放。这类自研方案的通病是只考虑了功能没考虑凭证的生命周期、撤销、刷新和防重放。OAuth2 的价值恰恰在于它把这些安全细节标准化了。它定义了一套完整的角色模型和授权流程资源所有者就是用户本人。客户端想要访问用户资源的应用比如工单系统、报表系统。授权服务器统一发放凭证的地方也就是单点登录的核心。资源服务器存放用户数据、需要校验凭证才能访问的服务。用 OAuth2 做单点登录本质上是把“认证”这一步委托给授权服务器业务系统只负责拿着授权服务器发的 token 去换用户身份。这样做的好处是职责单一业务系统不用再存密码、不用再管密码策略、不用再处理找回密码这些全部收敛到授权服务器一处。1.2 授权码模式为什么是首选OAuth2 有四种授权模式授权码、简化、密码、客户端凭证。做单点登录授权码模式Authorization Code几乎是唯一正确选择原因有三点。第一token 不经过浏览器前端。授权码模式里浏览器只拿到一个一次性的 code真正的 access_token 是后端服务器之间通过安全通道交换的。这样即使前端被 XSS 攻击攻击者也拿不到 token。第二支持 PKCE 扩展。现在的授权码模式基本都会配合 PKCEProof Key for Code Exchange防止授权码被拦截后冒用。虽然 PKCE 最初是为移动端设计的但 Web 端加上它也没坏处。第三可以配合 refresh_token 实现长期登录态。用户不用每次 token 过期都重新走一遍登录流程。密码模式看起来更简单直接拿用户名密码换 token但它要求业务系统接触用户密码这恰恰违背了单点登录“密码只在一处”的初衷所以只适合高度信任的第一方应用不推荐用于标准单点登录。1.3 整体架构分层一个典型的 OAuth2 单点登录架构我会把它拆成四层来看层级职责典型组件接入层统一入口、路由转发网关认证层登录、发码、发 token授权服务器资源层校验 token、返回用户信息用户中心服务业务层各业务系统工单、报表、监控等这里有个关键设计决策token 的校验放在网关还是放在各业务系统。我的建议是放在网关统一做。原因很简单如果每个业务系统都自己写一遍 token 校验逻辑迟早会出现某个系统校验漏了、或者校验逻辑不一致的情况。放在网关业务系统只需要从请求头里读网关透传过来的用户信息即可代码量能减少一大半。2. 核心流程拆解与关键参数设计2.1 授权码流程的完整时序整个登录流程走下来大致是这样一条链路。我用文字把每一步说清楚因为这里每一步都有坑。用户访问业务系统 AA 发现本地没有登录态于是把用户重定向到授权服务器的授权端点带上 client_id、redirect_uri、scope、state、code_challenge 等参数。授权服务器检查用户是否已登录。没登录就展示登录页登录成功后生成一个一次性的授权码 code重定向回 A 的 redirect_uri并原样带回 state。A 的后端拿到 code用 client_id、client_secret、code、code_verifier 去授权服务器的 token 端点换取 access_token 和 refresh_token。A 拿到 token 后可以调用用户中心服务获取用户信息建立本地会话。用户再访问业务系统 BB 同样重定向到授权服务器但此时授权服务器发现用户已有登录态直接发码用户无感知完成登录。第 5 步就是“单点”的精髓所在——授权服务器上的登录态是共享的所以第二个系统不需要用户再输密码。2.2 state 参数别把它当摆设state 参数很多人随手填个固定值这是很危险的做法。state 的作用是防止 CSRF 攻击攻击者可以构造一个带有自己授权码的回调链接诱导用户点击如果用户点击后业务系统直接用这个 code 换 token就会把攻击者的账号登录到用户浏览器上。正确做法是每次发起授权请求时生成一个随机 state存到用户会话里回调时比对。不一致就直接拒绝。这个随机值建议用加密安全的随机数生成器长度至少 16 字节。2.3 PKCE 的 code_challenge 计算PKCE 的核心是客户端生成一个随机的 code_verifier把它做 SHA256 哈希再 base64url 编码得到 code_challenge授权请求时带上 code_challenge换 token 时带上原始 code_verifier。授权服务器比对哈希值一致才发 token。// 生成 code_verifier 和 code_challenge 的示例 const crypto require(crypto); function base64UrlEncode(buffer) { return buffer.toString(base64) .replace(/\/g, -) .replace(/\//g, _) .replace(//g, ); } const codeVerifier base64UrlEncode(crypto.randomBytes(32)); const codeChallenge base64UrlEncode( crypto.createHash(sha256).update(codeVerifier).digest() );注意code_verifier 必须存在服务端会话里不能放在前端。如果放在前端PKCE 就失去意义了。2.4 token 的格式选择JWT 还是随机串这是设计阶段必须拍板的问题。两种方案各有取舍对比项JWT随机串 服务端存储校验方式本地验签无需查库必须查存储撤销能力弱需配合黑名单强删除即失效携带信息可内嵌用户信息需额外查询体积较大较小我的实践经验是access_token 用 JWTrefresh_token 用随机串。access_token 生命周期短一般 15 分钟到 2 小时用 JWT 可以让网关本地验签性能好refresh_token 生命周期长必须能撤销所以用随机串存服务端用户登出或改密码时直接删掉。JWT 的 payload 里建议放这些字段用户 ID、客户端 ID、签发时间、过期时间、scope。不要放敏感信息因为 JWT 只是签名不是加密payload 是 base64 编码的任何人都能解开看。3. 实操落地从授权服务器到网关校验3.1 授权服务器的核心端点实现授权服务器至少要提供四个端点授权端点、token 端点、用户信息端点、撤销端点。我用一个简化的 Node.js 示例说明 token 端点的核心逻辑。// token 端点核心逻辑伪代码突出关键校验 async function tokenEndpoint(req, res) { const { grant_type, code, redirect_uri, client_id, code_verifier } req.body; if (grant_type ! authorization_code) { return res.status(400).json({ error: unsupported_grant_type }); } // 1. 校验客户端 const client await findClient(client_id); if (!client) return res.status(401).json({ error: invalid_client }); // 2. 取出授权码校验是否过期、是否已使用 const authCode await findAuthCode(code); if (!authCode || authCode.used || authCode.expiresAt Date.now()) { return res.status(400).json({ error: invalid_grant }); } // 3. 校验 redirect_uri 与授权时一致 if (authCode.redirectUri ! redirect_uri) { return res.status(400).json({ error: invalid_grant }); } // 4. 校验 PKCE const expectedChallenge base64UrlEncode( crypto.createHash(sha256).update(code_verifier).digest() ); if (expectedChallenge ! authCode.codeChallenge) { return res.status(400).json({ error: invalid_grant }); } // 5. 标记授权码已使用防止重放 await markAuthCodeUsed(code); // 6. 签发 token const accessToken signJwt({ sub: authCode.userId, client_id, scope: authCode.scope }); const refreshToken generateRandomString(48); await saveRefreshToken(refreshToken, authCode.userId, client_id); res.json({ access_token: accessToken, token_type: Bearer, expires_in: 3600, refresh_token: refreshToken }); }这里有几个细节值得强调。授权码必须一次性使用用过就标记否则攻击者拿到 code 后可以反复换 token。授权码有效期要短一般 5 分钟足够太长会增加被拦截的风险。redirect_uri 必须严格比对不能只比对域名要完整匹配否则可能被开放重定向漏洞利用。3.2 网关统一校验的实现网关校验 token 的流程我一般这样设计// 网关过滤器核心逻辑Java 伪代码 public boolean preHandle(HttpServletRequest request) { String authHeader request.getHeader(Authorization); if (authHeader null || !authHeader.startsWith(Bearer )) { return reject(missing_token); } String token authHeader.substring(7); try { Claims claims Jwts.parser() .setSigningKey(publicKey) .parseClaimsJws(token) .getBody(); // 校验过期时间 if (claims.getExpiration().before(new Date())) { return reject(token_expired); } // 把用户信息透传给下游 request.setAttribute(userId, claims.getSubject()); request.setAttribute(scope, claims.get(scope)); return true; } catch (JwtException e) { return reject(invalid_token); } }网关验签用的是公钥私钥只在授权服务器手里。这样即使网关被攻破攻击者也无法伪造 token。这是非对称加密相比对称加密的核心优势。3.3 前端登录态的处理前端这块有个常见误区把 access_token 存 localStorage。我不推荐这么做因为 localStorage 能被任意同源 JS 读取一旦有 XSS 漏洞token 直接泄露。更稳妥的做法是access_token 只存在内存里refresh_token 放在 HttpOnly Secure SameSite 的 Cookie 里。access_token 过期时前端调用刷新接口后端用 Cookie 里的 refresh_token 换新的 access_token。这样即使 XSS 也拿不到 refresh_token。提示SameSite 属性建议设为 Lax 或 Strict。如果业务涉及跨站跳转回调Lax 通常够用Strict 最安全但可能影响部分跳转场景需要实测。3.4 登出与 token 撤销单点登录的登出比登录更容易被忽视。用户在一个系统点了登出其他系统还保持着登录态这体验就很割裂。标准做法是提供一个全局登出端点用户登出时先调用授权服务器的撤销端点把 refresh_token 作废然后清除授权服务器上的登录会话最后各业务系统通过前端轮询或 WebSocket 感知到登出事件清理本地会话。如果不想做实时通知退而求其次的方案是access_token 保持短生命周期登出后最多再过 15 分钟所有系统的 token 自然过期。这个折中方案在很多中小型系统里够用了。4. 常见问题排查与避坑经验4.1 跨域与 Cookie 问题速查跨域是单点登录里最高频的坑我整理了一张速查表现象可能原因排查方向回调后 Cookie 没带上SameSite 设置过严检查 SameSite 和 Secure 组合预检请求失败未允许 Authorization 头检查 CORS 配置的 allowedHeaders登录态丢失域名不一致确认 Cookie 的 Domain 覆盖所有子域重定向循环授权服务器自身也要求登录排除授权服务器路径的拦截这里重点说下 Cookie 的 Domain。如果业务系统是 a.example.com 和 b.example.com授权服务器是 sso.example.com那 Cookie 的 Domain 要设为.example.com这样三个子域都能共享。但要注意Domain 设得越宽安全边界越大所以不要设成顶级域。4.2 token 过期引发的连锁反应我遇到过最典型的问题access_token 设了 30 分钟结果用户在填一个长表单填到 25 分钟时提交token 刚好过期请求失败用户填的内容全丢了。解决办法有两个。一是前端做无感刷新在请求拦截器里判断 token 快过期时提前用 refresh_token 换新的。二是后端做宽限期token 过期后 60 秒内仍接受给刷新留出窗口。我一般两个都用体验最顺滑。无感刷新的关键是要加锁避免并发请求同时触发多次刷新。可以用一个 Promise 缓存第一个请求发起刷新后续请求都等这个 Promise 的结果。4.3 时钟偏移导致的验签失败JWT 验签时如果授权服务器和网关的服务器时间差了哪怕几十秒就可能出现“token 刚签发就过期”或者“token 已过期却还能用”的诡异现象。处理办法是在验签时设置时钟容差clock skew一般给 60 秒。同时所有服务器必须开启 NTP 时间同步。这个坑很隐蔽因为本地测试时两台机器时间往往一致一上生产环境多台机器就暴露了。4.4 授权码被重放的排查如果发现日志里有同一个 code 被多次用于换 token基本可以确定是重放攻击或者客户端重试逻辑有问题。排查步骤先看授权码是否被正确标记为已使用再看客户端是不是在 token 请求超时后无脑重试。token 端点必须保证幂等性处理——同一个 code 第二次来直接返回错误而不是再发一次 token。如果客户端确实需要重试应该重新走一遍授权流程拿新 code。4.5 我的几条实操心得第一scope 要设计得细。不要所有客户端都给一个all权限按业务划分成user:read、order:write这种粒度。这样即使某个客户端的 token 泄露影响范围也可控。第二client_secret 要能轮换。设计时就支持一个客户端配置多个 secret轮换时新旧并存一段时间避免换 secret 导致服务中断。第三日志要脱敏。token、code、client_secret 这些绝对不能明文打进日志。我见过有团队把完整 token 打进访问日志结果日志被同步到第三方平台等于把钥匙挂在了门上。第四压测要覆盖 token 刷新场景。很多系统登录压测没问题但大量 token 同时过期时刷新接口被打爆。刷新接口的 QPS 承载能力要单独评估。5. 安全加固与扩展场景5.1 必须开启的安全措施清单把单点登录做到“能用”和做到“安全”中间差着不少工作。下面这些措施我建议一条条对照落实强制 HTTPS所有涉及 token 传输的端点必须走 HTTPS包括内网调用。redirect_uri 白名单授权服务器只接受预先注册的回调地址禁止通配符。token 绑定客户端access_token 里带上 client_id资源服务器校验时确认 token 是发给自己的。刷新令牌轮换每次用 refresh_token 换新 token 时旧的 refresh_token 立即作废发一个新的。这样即使 refresh_token 泄露攻击者用一次后真正的用户就会发现异常。登录失败限流按账号和 IP 双维度限流防止暴力破解。异常登录检测异地、新设备登录时触发二次验证。5.2 多端登录与设备管理现在的系统往往要支持 Web、移动端、桌面端同时登录。OAuth2 本身不限制一个用户能有多少个 token所以需要业务层自己控制。我的做法是每个设备一个独立的 refresh_tokenaccess_token 不区分设备。用户可以在“设备管理”页面看到所有活跃设备手动踢掉某个设备。踢设备本质上就是删掉对应的 refresh_token等 access_token 过期后该设备就自动掉线了。如果要求踢掉后立即生效就需要维护一个 access_token 黑名单网关验签后再查一次黑名单。这会牺牲一点性能但对安全要求高的场景值得。5.3 与第三方登录的整合很多系统既要支持内部账号单点登录又要支持第三方账号登录。这两套体系可以统一到同一个授权服务器下内部账号走标准的授权码流程第三方账号走各自的 OAuth 流程但最终都映射到授权服务器内部的用户 ID签发统一的 token。关键点是账号绑定。用户第一次用第三方账号登录时如果系统里已有同邮箱的内部账号要引导用户确认绑定而不是自动合并。自动合并有账号劫持风险——如果第三方平台的邮箱验证不严攻击者可能用别人的邮箱注册第三方账号然后自动接管内部账号。5.4 微服务场景下的 token 传递在微服务架构里网关校验完 token 后下游服务之间怎么传递用户身份有两种做法。一种是继续透传原始 token每个服务都自己验签。好处是无状态坏处是每个服务都要拿到公钥、都要写验签逻辑。另一种是网关把用户信息放进内部请求头比如X-User-Id、X-User-Scope下游服务直接读。好处是下游简单坏处是这些头必须由网关强制覆盖防止外部伪造。如果网关没做好头部的清洗外部请求带个X-User-Id就能冒充任意用户这是很严重的安全漏洞。我倾向于第二种但前提是网关必须无条件覆盖这些内部头并且内部服务不对外暴露。如果内部服务可能被直接访问那还是老老实实每个服务验签。6. 性能优化与监控告警6.1 验签性能优化JWT 验签是 CPU 密集型操作尤其是 RS256 这种非对称算法。在 QPS 高的网关验签可能成为瓶颈。优化手段有几个。一是缓存公钥不要每次验签都去拉 JWKS。二是用 ES256 替代 RS256椭圆曲线算法在同等安全强度下更快、密钥更短。三是热点 token 缓存验签结果同一个 token 在有效期内多次请求可以缓存“验签通过”的结果key 用 token 的哈希值。不过缓存验签结果要小心缓存时间不能超过 token 剩余有效期否则 token 撤销后缓存还在放行。6.2 关键监控指标单点登录是全局入口它挂了整个公司都用不了系统所以监控必须到位。我一般盯这几个指标指标含义告警阈值建议登录成功率成功登录 / 总登录尝试低于 95% 告警token 端点 P99 延迟换 token 的响应时间超过 500ms 告警授权码使用率已使用 code / 已发放 code异常偏低说明流程中断刷新失败率刷新失败 / 刷新请求超过 1% 告警验签失败率验签失败 / 验签请求突增说明可能被攻击登录成功率突然下降往往是授权服务器或用户中心出了问题验签失败率突增可能是有人在拿伪造 token 试探也可能是密钥轮换没同步。6.3 灰度与回滚单点登录改造涉及所有系统不可能一次性全切。我的建议是按系统灰度先切一个边缘的、影响小的系统跑一周没问题再切核心系统。灰度期间两套登录方式并存用户可以选择用新的单点登录也可以走老的本地登录。回滚方案要提前准备好。最怕的是授权服务器上线后发现严重 bug但所有系统已经切过去了回滚都来不及。所以灰度期间一定要保留老登录入口并且明确回滚的触发条件和操作步骤。密钥轮换也要灰度。新密钥发布后授权服务器用新私钥签发 token网关同时信任新旧两个公钥等所有旧 token 都过期后再移除旧公钥。这个过渡期至少要是 access_token 生命周期的一倍。7. 我踩过的几个真实坑说几个文档里不会写、但实际一定会遇到的问题。第一个坑是重定向地址的编码。redirect_uri 里如果带了查询参数比如?from/dashboard在授权请求里必须做 URL 编码否则参数会被截断。我见过因为没编码导致回调后跳转丢失、用户回到首页的情况排查了半天才发现是编码问题。第二个坑是并发刷新。前端多个请求同时发现 token 过期同时发起刷新结果第一个刷新成功后 refresh_token 轮换了后面几个用旧 refresh_token 刷新全部失败用户被踢下线。解决办法就是前面说的加锁用一个共享 Promise 保证同一时间只有一个刷新请求。第三个坑是移动端的 WebView。移动端 App 内嵌 WebView 做单点登录时Cookie 的存储和普通浏览器不一样有些 WebView 默认不持久化 Cookie导致每次打开都要重新登录。需要在 WebView 初始化时显式开启 Cookie 持久化并且处理好 App 原生登录态和 WebView 登录态的同步。第四个坑是时间同步。前面提过时钟偏移这里再强调一次因为真的太常见了。容器化部署后容器时间默认跟宿主机走如果宿主机 NTP 没配好容器时间就是错的。上线前一定要检查所有节点的时间偏差。第五个坑是日志里的 token 泄露。有一次排查问题发现某个中间件把完整的请求头打进了日志包括 Authorization。后来我们加了个日志脱敏规则所有匹配Bearer xxx的内容统一替换成Bearer ***。这个规则建议在项目初期就加上事后补很麻烦。8. 后续可扩展的方向单点登录做完只是起点后面还有不少可以深挖的地方。一是接入 OIDC。OAuth2 只解决授权不解决认证。OIDCOpenID Connect在 OAuth2 之上加了一层 ID Token标准化了“我是谁”这个问题。如果未来要对接更多第三方系统直接上 OIDC 会比纯 OAuth2 更规范。二是做细粒度授权。现在 token 里带的是 scope粒度比较粗。如果业务需要更细的权限控制可以引入 UMAUser-Managed Access或者自己设计基于资源的权限模型把权限判断下沉到资源服务器。三是无密码登录。结合 WebAuthn用户可以用指纹、人脸、硬件密钥登录彻底告别密码。这在大企业内网场景下体验提升很明显也避免了弱密码问题。四是风险自适应认证。根据登录时的设备指纹、地理位置、行为特征动态调整认证强度。低风险直接放行高风险要求二次验证。这套东西做起来复杂但对安全敏感的业务价值很大。单点登录这个事说难不难说简单也不简单。核心流程就那么几步但每一步的安全细节、边界情况、性能考量加起来能写满一整本笔记。我的建议是先把授权码流程跑通再逐步加固安全和体验不要一上来就追求大而全。真正上线后你会发现最花时间的往往不是主流程而是那些边边角角的兼容和排查。把日志打全、把监控做好、把回滚方案备好比什么都重要。