1. 项目概述为什么我们需要一个统一的登录门户在微服务架构成为主流的今天一个典型的Spring Cloud应用可能由十几个甚至几十个独立的服务组成。想象一下你作为用户访问一个电商平台浏览商品商品服务、查看订单订单服务、管理地址用户服务都需要分别登录一次这体验无疑是灾难性的。这就是“单点登录”要解决的核心痛点一次登录处处通行。而OAuth 2.0则是实现这个目标的行业标准协议。它定义了资源所有者用户、客户端我们的前端应用、授权服务器和资源服务器之间的安全交互流程。简单来说OAuth 2.0让用户在一个地方比如公司的统一认证中心授权后其他所有接入该中心的应用都能安全地获取到用户的身份信息而无需用户再次输入密码。那么为什么选择Sa-Token来实现呢在我过去几年的微服务实践中尝试过Spring Security OAuth2、Keycloak等多种方案。Spring Security OAuth2功能强大但配置繁琐学习曲线陡峭Keycloak作为专业IdP身份提供商又显得过于重型。Sa-Token的出现恰好填补了轻量、易用与功能完备之间的空白。它基于Java与Spring Boot/Cloud生态无缝集成用极简的API封装了复杂的认证授权逻辑让开发者能更专注于业务本身。这个项目就是基于Sa-Token OAuth2模块构建一个适用于Spring Boot Spring Cloud环境的、生产可用的单点登录实战方案并附上我踩过的所有坑和解决方案。2. 核心架构设计与组件选型2.1 整体架构蓝图一个标准的OAuth2单点登录系统通常包含以下几个核心角色我们的实战架构也将围绕它们展开客户端需要接入SSO的各个业务应用如订单服务、用户服务等。它们不直接处理登录而是引导用户去认证中心登录并接收认证中心颁发的令牌。认证中心整个系统的核心独立的服务。负责用户的登录认证、颁发访问令牌、校验令牌有效性。它持有所有用户凭证和客户端注册信息。资源服务器提供受保护API的业务服务。它不负责认证只负责验证客户端带来的令牌是否有效、是否有权限访问特定资源。在我们的Spring Cloud体系中认证中心作为一个独立的auth-service部署。各个业务服务客户端/资源服务器通过引入Sa-Token依赖并进行简单配置与认证中心通信。通信的核心是令牌通常采用JWT格式因其自包含、无状态的特点非常适合分布式场景。2.2 为什么是授权码模式OAuth2.0定义了多种授权模式如密码模式、客户端模式、隐式模式和授权码模式。对于Web应用的单点登录授权码模式是安全性和适用性最高的选择也是本次实战采用的模式。它的流程可以类比为“机场安检换登机牌”你用户首先要去航空公司柜台认证中心登录页出示身份证输入账号密码办理值机柜台验证通过后不会直接把登机牌令牌给你而是给你一个兑换凭证授权码。你拿着这个凭证去指定的机器客户端后台兑换真正的登机牌访问令牌。这个过程避免了令牌直接暴露在浏览器地址栏等不安全环境。密码模式虽然简单但需要客户端收集用户密码违背了OAuth“第三方应用不应接触用户密码”的安全原则已不推荐用于第三方应用。隐式模式适用于纯前端应用但令牌直接返回给浏览器安全性较低。因此授权码模式配合PKCE扩展已成为现代Web应用SSO的事实标准。2.3 核心依赖与版本锁定在pom.xml中我们需要引入以下核心依赖。版本管理是关键不兼容的版本会导致各种诡异问题。!-- 认证中心 客户端/资源服务器 均需要 -- dependency groupIdcn.dev33/groupId artifactIdsa-token-spring-boot-starter/artifactId version1.34.0/version !-- 请使用当时最新稳定版 -- /dependency !-- OAuth2.0 模块 -- dependency groupIdcn.dev33/groupId artifactIdsa-token-oauth2/artifactId version1.34.0/version /dependency !-- Redis集成 (用于分布式会话/令牌存储必须) -- dependency groupIdcn.dev33/groupId artifactIdsa-token-dao-redis/artifactId version1.34.0/version /dependency dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependency注意Sa-Token的核心版本如sa-token-spring-boot-starter与OAuth2模块版本必须严格保持一致。我曾在一次升级中忽略了这一点导致SaCheckLogin注解完全失效排查了半天才发现是版本冲突。建议使用Maven的properties统一管理这些版本号。3. 认证中心服务端详细配置与实现认证中心是大脑配置必须严谨。我们创建一个独立的Spring Boot应用例如auth-server。3.1 基础配置与Redis连接首先在application.yml中配置核心参数和Redis。Redis在这里至关重要用于存储授权码、访问令牌、刷新令牌的关联关系实现分布式会话。server: port: 9000 spring: application: name: auth-server redis: host: localhost port: 6379 database: 0 lettuce: pool: max-active: 8 max-idle: 8 min-idle: 0 sa-token: # 令牌名称也是提交令牌时参数的名称 token-name: satoken # 令牌有效期单位秒 默认30天-1代表永不过期 timeout: 2592000 # 临时令牌有效期授权码 默认5分钟 activity-timeout: 300 # 是否允许同一账号并发登录 为true时允许一起登录为false时新登录挤掉旧登录 is-concurrent: true # 在多人登录同一账号时是否共用一个token 为true时所有登录共用一个token为false时每次登录新建一个token is-share: false # token风格uid-随机字符串 token-style: uuid # 是否输出操作日志 is-log: true # OAuth2.0 配置 oauth2: is-code: true # 是否打开授权码模式 is-implicit: false # 是否打开隐式模式生产环境建议关闭 # 客户端信息配置可以配置多个 client: # 客户端标识clientId test-client: client-id: test-client # 客户端ID client-secret: test-secret # 客户端密钥 allow-url: http://localhost:8081,http://localhost:8082 # 允许的授权回调地址多个用逗号分隔 contract-scope: userinfo # 合约式授权范围客户端默认拥有的权限 is-auto-mode: true # 是否自动判断此客户端是否在授权时自动点击确认3.2 核心配置类与客户端信息加载上述YAML配置了静态客户端。但在生产环境中客户端信息通常存储在数据库。我们需要通过一个配置类来动态加载。Configuration public class SaOAuth2ServerConfig { Autowired private ClientDetailsService clientDetailsService; // 你自己的客户端信息服务 /** * 配置OAuth2服务端 */ Bean public SaOAuth2Template saOAuth2Template() { return new SaOAuth2Template() // 自定义ClientModel的查询方式从数据库查询 .setClientModelLoader(clientId - { // 从数据库查询客户端信息并转换为 SaClientModel YourClientDetail detail clientDetailsService.loadClientByClientId(clientId); if (detail null) { return null; } return SaClientModel .newBuilder() .clientId(detail.getClientId()) .clientSecret(detail.getClientSecret()) .allowUrl(detail.getAllowUrls()) // 允许的回调地址多个用逗号隔开 .contractScope(detail.getContractScope()) .build(); }) // 自定义授权页面的代码 .setConfirmPageHtml((clientId, scope) - { // 这里可以返回一个自定义的HTML字符串例如Thymeleaf模板渲染的结果 return h1请确认授权/h1p客户端 clientId /pp权限范围 scope /p form method\post\button type\submit\确认授权/button/form; }); } /** * 注册 Sa-Token 的全局过滤器用于拦截并处理OAuth2请求 */ Bean public SaServletFilter getSaServletFilter() { return new SaServletFilter() .addInclude(/oauth2/*) // 拦截所有oauth2开头的请求 .setAuth(obj - { // 此处可以写一些预处理逻辑例如日志记录 }); } }实操心得setConfirmPageHtml这个配置非常有用。默认的授权确认页很简陋你可以在这里集成公司的UI组件库做一个风格统一的授权页。我曾在这里直接返回一个Vue组件的HTML通过Nginx代理静态资源实现了完全自定义的漂亮界面。3.3 用户登录与授权端点暴露认证中心需要提供标准的OAuth2端点。Sa-Token已经内置了这些端点我们只需要提供一个用户登录的接口即可。RestController RequestMapping(/oauth2) public class OAuth2ServerController { /** * 用户登录接口提供给认证中心自己的登录页使用 */ PostMapping(/doLogin) public SaResult doLogin(RequestParam String username, RequestParam String password) { // 1. 模拟从数据库查询用户信息生产环境需替换为真实查询 if(!zhang.equals(username) || !123456.equals(password)) { return SaResult.error(账号或密码错误); } // 2. 会话登录Sa-Token核心登录方法 StpUtil.login(10001); // 10001 是模拟的用户ID // 3. 返回登录成功信息及Token return SaResult.data(StpUtil.getTokenInfo()); } /** * 用户信息接口资源服务器校验令牌后调用此接口获取用户详情 */ GetMapping(/userinfo) public SaResult userinfo() { // 1. 获取当前登录用户ID (从Token中解析Sa-Token自动完成) Object userId StpUtil.getLoginId(); // 2. 模拟查询用户信息生产环境从数据库或缓存查 MapString, Object user new HashMap(); user.put(id, userId); user.put(name, 张三); user.put(avatar, https://xxx.com/avatar.png); user.put(perms, Arrays.asList(user.add, user.delete)); // 用户权限列表 return SaResult.data(user); } }注意StpUtil.login(id)是Sa-Token的核心登录方法它会在Redis中创建一个以这个id为key的Token令牌。这个令牌就是后续OAuth2流程中“用户已登录”状态的凭证。/userinfo端点是一个标准的userinfo端点资源服务器拿到访问令牌后可以调用此端点获取用户的详细信息。4. 客户端与资源服务器集成实战现在我们来配置需要接入SSO的业务服务它同时作为OAuth2的客户端和资源服务器。4.1 客户端配置在业务服务的application.yml中配置sa-token: oauth2: client: # 客户端模式授权码 mode: code # 认证中心地址 auth-url: http://localhost:9000/oauth2/authorize # 获取Token的地址 token-url: http://localhost:9000/oauth2/token # 用户信息地址 userinfo-url: http://localhost:9000/oauth2/userinfo # 客户端id client-id: test-client # 客户端密钥 client-secret: test-secret # 回调地址必须和认证中心配置的allow-url之一完全匹配 redirect-url: http://localhost:8081/sso/callback4.2 核心控制器处理回调与登录状态客户端需要两个核心接口1. 跳转到认证中心登录2. 处理认证中心回调。RestController public class SsoClientController { /** * 首页判断当前是否在本系统登录 */ RequestMapping(/) public SaResult index() { if(StpUtil.isLogin()) { // 已登录从会话中获取用户信息 Object userId StpUtil.getLoginId(); return SaResult.data(已登录用户id: userId , 详细信息: StpUtil.getSession().get(user)); } else { // 未登录提供登录链接 String authUrl SaOAuth2Client.newAuthRequest() // 创建授权请求 .setClientId(test-client) .setRedirectUri(http://localhost:8081/sso/callback) .setResponseType(code) .setScope(userinfo) // 申请的权限范围 .buildQueryUrl(); // 构建完整的授权地址 return SaResult.data(未登录a href\ authUrl \点击登录/a); } } /** * 单点登录回调地址核心 */ RequestMapping(/sso/callback) public SaResult callback(String code, String state) { // 1. 用授权码换取访问令牌 SaOAuth2Client saOAuth2Client new SaOAuth2Client(test-client, test-secret); SaOAuth2Token token saOAuth2Client.getAccessTokenByCode(code, http://localhost:8081/sso/callback); // 2. 用访问令牌获取用户信息 MapString, Object userInfo saOAuth2Client.getUserinfo(token.getAccessToken()); // 3. 在本地系统进行登录关键步骤 // 通常使用userInfo中的唯一标识如uid作为本地登录id String localUserId sso_ userInfo.get(id); // 建议加前缀避免与本地用户ID冲突 StpUtil.login(localUserId); // 4. 将用户信息存入本地会话可选但推荐 StpUtil.getSession().set(user, userInfo); // 5. 重定向到首页或原始访问页面 return SaResult.data(登录成功).set(tokenInfo, token).set(userInfo, userInfo); } /** * 受保护的资源API示例 */ SaCheckLogin // Sa-Token注解检查是否登录未登录将抛出异常 GetMapping(/api/user/profile) public SaResult profile() { Object userId StpUtil.getLoginId(); MapString, Object user (MapString, Object) StpUtil.getSession().get(user); return SaResult.data(您的个人信息 user); } }4.3 全局异常处理与拦截器配置为了统一处理未登录、权限不足等情况需要配置全局异常处理器。RestControllerAdvice public class GlobalExceptionHandler { /** * 拦截所有未登录异常 */ ExceptionHandler(NotLoginException.class) public SaResult handlerNotLoginException(NotLoginException e) { // 根据异常类型细分提示 String message; switch (e.getType()) { case NotLoginException.NOT_TOKEN: message 未提供Token; break; case NotLoginException.INVALID_TOKEN: message Token无效; break; case NotLoginException.TOKEN_TIMEOUT: message Token已过期; break; case NotLoginException.BE_REPLACED: message 账号已在别处登录; break; case NotLoginException.KICK_OUT: message 已被强制下线; break; default: message 当前会话未登录; } // 返回401状态码和跳转登录的地址 return SaResult.error(message).setCode(401); } /** * 拦截所有权限异常 */ ExceptionHandler(NotPermissionException.class) public SaResult handlerNotPermissionException(NotPermissionException e) { return SaResult.error(无此权限 e.getPermission()); } }同时为了让SaCheckLogin等注解生效需要在配置类中注册拦截器。Configuration public class SaTokenConfigure implements WebMvcConfigurer { /** * 注册Sa-Token的注解拦截器打开注解式鉴权功能 */ Override public void addInterceptors(InterceptorRegistry registry) { // 注册注解拦截器并排除不需要拦截的路径 registry.addInterceptor(new SaAnnotationInterceptor()).addPathPatterns(/**); } }5. 深度排查八大常见问题与解决方案实录在实际部署和联调中我遇到了各种各样的问题。下面这个表格是我整理的“血泪史”希望能帮你快速排雷。问题现象可能原因排查步骤与解决方案1. 点击登录后回调地址报错invalid redirect_uri这是最常见的问题。回调地址未在认证中心的allow-url中配置或格式不匹配。1. 检查客户端redirect-url配置的完整性和精确性包括http/https、端口、路径。2. 检查认证中心sa-token.oauth2.client.[clientId].allow-url配置确保回调地址完全匹配其中之一。支持逗号分隔多个地址。3.生产环境注意如果经过Nginx代理客户端获取到的请求地址可能是内网地址需在Nginx或代码中正确设置X-Forwarded-Proto和X-Forwarded-Host头部。2. 授权码兑换令牌时失败提示invalid client客户端ID或密钥错误或者认证中心的ClientModel加载器如从数据库读返回了null。1. 核对客户端client-id和client-secret确保与认证中心注册信息完全一致注意大小写和空格。2. 在认证中心SaOAuth2Template.setClientModelLoader方法内加日志或断点确认是否能根据clientId正确查询到客户端信息。3. 检查Redis连接是否正常有时客户端信息会缓存到Redis。3. 登录成功但进入业务系统后依然显示未登录客户端回调接口中用SSO返回的用户信息进行StpUtil.login()时使用的key与业务系统其他接口校验登录状态时使用的key不一致或未持久化。1.核心确保StpUtil.login(id)中的id是唯一且稳定的通常使用SSO用户中心返回的uid或username。建议拼接前缀如sso_uid避免与本地用户ID冲突。2. 检查Redis配置。客户端的登录状态Token也存储在Redis中。确保客户端应用的Redis配置正确且与认证中心共用或互通同一个Redis服务/集群。3. 检查Cookie域。如果多个业务系统域名不同需要在SaTokenConfig中配置token-domain为父级域名如.company.com并确保is-read-cookie为true。4. 令牌过期后无法自动刷新默认的授权码模式Sa-Token客户端不会自动刷新令牌。需要手动处理TokenInvalidException。1. 在全局异常处理器中捕获TokenInvalidException。2. 在异常处理逻辑中检查是否存在刷新令牌refresh_token。3. 如果存在则调用认证中心的/oauth2/refresh接口需自行实现或使用SaOAuth2Client的refreshAccessToken方法获取新的访问令牌。4. 更新本地会话的Token并重试原请求或引导用户重新授权。这是一个进阶功能需要仔细设计流程。5. 跨域问题在回调时出现CORS错误认证中心的授权接口和令牌接口被前端直接调用但未配置CORS。1. 最彻底的解决方案不要从前端直接调用认证中心接口。所有OAuth2流程应通过后端代理或重定向完成。授权请求是302重定向令牌请求是后端服务间的调用天然避免CORS。2. 如果确有需要在认证中心通过CrossOrigin注解或WebMvcConfigurer配置CORS。务必严格限制Origin不要使用*。6. 集成Spring Security后Sa-Token注解失效Spring Security的过滤器链优先级高于Sa-Token可能拦截请求并返回403。1. 如果不需要Spring Security的登录认证功能可以考虑在SSO客户端项目中排除Spring Security依赖。2. 如果需要Spring Security做其他事情如方法级安全则需配置Spring Security忽略OAuth2回调路径和API路径.requestMatchers(/sso/callback, /api/**).permitAll()。3. 调整过滤器顺序非常复杂不推荐新手尝试。7. 高并发下登录状态混乱或踢人下线不生效Redis配置或Sa-Token配置不当导致会话覆盖或并发问题。1. 检查sa-token.is-concurrent和sa-token.is-share配置。is-concurrentfalse时新登录会踢掉旧登录。is-sharetrue时同一账号所有端共享一个Token。根据业务场景选择。2.检查Redis连接池配置。高并发下连接数不足会导致超时和状态不一致。适当调大spring.redis.lettuce.pool.max-active。3. 考虑使用Redisson代替Lettuce作为Sa-Token的Redis客户端其对分布式锁的支持更好。8. 日志里大量NotLoginException但用户感觉正常可能是爬虫、健康检查或前端静态资源请求触发了登录校验。1. 在注册Sa-Token拦截器时使用addPathPatterns和excludePathPatterns精确排除不需要鉴权的路径如/favicon.ico,/error,/actuator/health,/static/**等。2. 在前端避免在全局请求拦截器中无条件地携带Token访问所有接口。3. 使用SaIgnore注解标注不需要登录的控制器方法。6. 生产环境进阶配置与优化建议当系统从本地开发走向生产环境时以下几个方面的优化至关重要。6.1 安全性加固使用HTTPS绝对必须。OAuth2流程中的授权码、令牌都在网络传输使用HTTPS是防止中间人攻击的基础。为认证中心和所有客户端服务配置有效的SSL证书。客户端密钥管理不要将client-secret硬编码在配置文件中。使用环境变量、配置中心如Nacos、Apollo或云厂商的密钥管理服务。授权码与令牌有效期缩短授权码activity-timeout的有效期例如5分钟。访问令牌timeout可根据业务设置如2小时。同时一定要启用刷新令牌并为其设置较长的有效期如7天。PKCE扩展对于公共客户端如SPA单页应用强烈建议启用PKCE。Sa-Token OAuth2模块也支持PKCE需要在创建授权请求时设置code_challenge和code_challenge_method。6.2 性能与高可用Redis高可用会话和令牌存储强烈依赖Redis。生产环境必须使用Redis哨兵或集群模式避免单点故障。在sa-token配置中可以配置多个Redis节点。认证中心集群化认证中心本身是无状态的状态在Redis因此可以轻松水平扩展。通过Nginx等负载均衡器将请求分发到多个认证中心实例。JWT替代部分Redis查询虽然Sa-Token默认将Token与权限关系存Redis但可以考虑使用JWT格式的Token将一些基本声明如用户ID、过期时间编码在Token本身。资源服务器无需每次请求都查询认证中心或Redis只需验证签名即可。这需要自定义SaTokenTemplate的实现。6.3 监控与审计日志集中收集在认证中心和客户端的关键节点如登录成功/失败、令牌颁发/刷新、权限校验失败打上详细的日志并接入ELK或类似日志平台。审计日志记录所有重要的OAuth2事件包括谁用户、客户端、在什么时间、从哪里IP、做了什么操作授权、访问资源、结果如何。这对于安全事件追溯至关重要。健康检查与熔断客户端服务需要监控与认证中心的连接状态。如果认证中心不可用应有降级策略如使用本地缓存的黑白名单进行基本校验或直接拒绝服务并给出友好提示。7. 与Spring Cloud Gateway的集成方案在微服务架构中我们通常使用API网关如Spring Cloud Gateway作为统一入口。网关可以统一处理SSO逻辑让下游业务服务完全无感知。方案思路网关拦截所有请求检查请求中是否携带Token可从Cookie或Header获取。如果无Token重定向到认证中心登录。如果有Token网关作为客户端向认证中心校验Token有效性并获取用户基本信息。网关将用户ID等信息以请求头如X-User-Id的形式转发给下游业务服务。业务服务只需信任网关转发的头部信息即可无需再集成Sa-Token客户端模块。这种模式解耦了业务服务和认证逻辑业务服务变得更纯粹。实现此方案需要在Spring Cloud Gateway中编写自定义的全局过滤器核心是调用SaOAuth2Client的checkAccessToken或getUserinfo方法。这虽然增加了网关的复杂性但带来了架构上的清晰度是大型微服务系统的常见选择。整个集成过程从架构设计到细节调试考验的是对OAuth2协议流程的深刻理解和对Sa-Token组件特性的熟练运用。记住单点登录不仅仅是技术的拼接更是对用户体验和安全边界的一种设计。多动手测试善用日志排查这套组合拳一定能帮你构建出稳定可靠的统一身份认证体系。
基于Sa-Token与OAuth2实现Spring Cloud微服务单点登录实战
1. 项目概述为什么我们需要一个统一的登录门户在微服务架构成为主流的今天一个典型的Spring Cloud应用可能由十几个甚至几十个独立的服务组成。想象一下你作为用户访问一个电商平台浏览商品商品服务、查看订单订单服务、管理地址用户服务都需要分别登录一次这体验无疑是灾难性的。这就是“单点登录”要解决的核心痛点一次登录处处通行。而OAuth 2.0则是实现这个目标的行业标准协议。它定义了资源所有者用户、客户端我们的前端应用、授权服务器和资源服务器之间的安全交互流程。简单来说OAuth 2.0让用户在一个地方比如公司的统一认证中心授权后其他所有接入该中心的应用都能安全地获取到用户的身份信息而无需用户再次输入密码。那么为什么选择Sa-Token来实现呢在我过去几年的微服务实践中尝试过Spring Security OAuth2、Keycloak等多种方案。Spring Security OAuth2功能强大但配置繁琐学习曲线陡峭Keycloak作为专业IdP身份提供商又显得过于重型。Sa-Token的出现恰好填补了轻量、易用与功能完备之间的空白。它基于Java与Spring Boot/Cloud生态无缝集成用极简的API封装了复杂的认证授权逻辑让开发者能更专注于业务本身。这个项目就是基于Sa-Token OAuth2模块构建一个适用于Spring Boot Spring Cloud环境的、生产可用的单点登录实战方案并附上我踩过的所有坑和解决方案。2. 核心架构设计与组件选型2.1 整体架构蓝图一个标准的OAuth2单点登录系统通常包含以下几个核心角色我们的实战架构也将围绕它们展开客户端需要接入SSO的各个业务应用如订单服务、用户服务等。它们不直接处理登录而是引导用户去认证中心登录并接收认证中心颁发的令牌。认证中心整个系统的核心独立的服务。负责用户的登录认证、颁发访问令牌、校验令牌有效性。它持有所有用户凭证和客户端注册信息。资源服务器提供受保护API的业务服务。它不负责认证只负责验证客户端带来的令牌是否有效、是否有权限访问特定资源。在我们的Spring Cloud体系中认证中心作为一个独立的auth-service部署。各个业务服务客户端/资源服务器通过引入Sa-Token依赖并进行简单配置与认证中心通信。通信的核心是令牌通常采用JWT格式因其自包含、无状态的特点非常适合分布式场景。2.2 为什么是授权码模式OAuth2.0定义了多种授权模式如密码模式、客户端模式、隐式模式和授权码模式。对于Web应用的单点登录授权码模式是安全性和适用性最高的选择也是本次实战采用的模式。它的流程可以类比为“机场安检换登机牌”你用户首先要去航空公司柜台认证中心登录页出示身份证输入账号密码办理值机柜台验证通过后不会直接把登机牌令牌给你而是给你一个兑换凭证授权码。你拿着这个凭证去指定的机器客户端后台兑换真正的登机牌访问令牌。这个过程避免了令牌直接暴露在浏览器地址栏等不安全环境。密码模式虽然简单但需要客户端收集用户密码违背了OAuth“第三方应用不应接触用户密码”的安全原则已不推荐用于第三方应用。隐式模式适用于纯前端应用但令牌直接返回给浏览器安全性较低。因此授权码模式配合PKCE扩展已成为现代Web应用SSO的事实标准。2.3 核心依赖与版本锁定在pom.xml中我们需要引入以下核心依赖。版本管理是关键不兼容的版本会导致各种诡异问题。!-- 认证中心 客户端/资源服务器 均需要 -- dependency groupIdcn.dev33/groupId artifactIdsa-token-spring-boot-starter/artifactId version1.34.0/version !-- 请使用当时最新稳定版 -- /dependency !-- OAuth2.0 模块 -- dependency groupIdcn.dev33/groupId artifactIdsa-token-oauth2/artifactId version1.34.0/version /dependency !-- Redis集成 (用于分布式会话/令牌存储必须) -- dependency groupIdcn.dev33/groupId artifactIdsa-token-dao-redis/artifactId version1.34.0/version /dependency dependency groupIdorg.apache.commons/groupId artifactIdcommons-pool2/artifactId /dependency注意Sa-Token的核心版本如sa-token-spring-boot-starter与OAuth2模块版本必须严格保持一致。我曾在一次升级中忽略了这一点导致SaCheckLogin注解完全失效排查了半天才发现是版本冲突。建议使用Maven的properties统一管理这些版本号。3. 认证中心服务端详细配置与实现认证中心是大脑配置必须严谨。我们创建一个独立的Spring Boot应用例如auth-server。3.1 基础配置与Redis连接首先在application.yml中配置核心参数和Redis。Redis在这里至关重要用于存储授权码、访问令牌、刷新令牌的关联关系实现分布式会话。server: port: 9000 spring: application: name: auth-server redis: host: localhost port: 6379 database: 0 lettuce: pool: max-active: 8 max-idle: 8 min-idle: 0 sa-token: # 令牌名称也是提交令牌时参数的名称 token-name: satoken # 令牌有效期单位秒 默认30天-1代表永不过期 timeout: 2592000 # 临时令牌有效期授权码 默认5分钟 activity-timeout: 300 # 是否允许同一账号并发登录 为true时允许一起登录为false时新登录挤掉旧登录 is-concurrent: true # 在多人登录同一账号时是否共用一个token 为true时所有登录共用一个token为false时每次登录新建一个token is-share: false # token风格uid-随机字符串 token-style: uuid # 是否输出操作日志 is-log: true # OAuth2.0 配置 oauth2: is-code: true # 是否打开授权码模式 is-implicit: false # 是否打开隐式模式生产环境建议关闭 # 客户端信息配置可以配置多个 client: # 客户端标识clientId test-client: client-id: test-client # 客户端ID client-secret: test-secret # 客户端密钥 allow-url: http://localhost:8081,http://localhost:8082 # 允许的授权回调地址多个用逗号分隔 contract-scope: userinfo # 合约式授权范围客户端默认拥有的权限 is-auto-mode: true # 是否自动判断此客户端是否在授权时自动点击确认3.2 核心配置类与客户端信息加载上述YAML配置了静态客户端。但在生产环境中客户端信息通常存储在数据库。我们需要通过一个配置类来动态加载。Configuration public class SaOAuth2ServerConfig { Autowired private ClientDetailsService clientDetailsService; // 你自己的客户端信息服务 /** * 配置OAuth2服务端 */ Bean public SaOAuth2Template saOAuth2Template() { return new SaOAuth2Template() // 自定义ClientModel的查询方式从数据库查询 .setClientModelLoader(clientId - { // 从数据库查询客户端信息并转换为 SaClientModel YourClientDetail detail clientDetailsService.loadClientByClientId(clientId); if (detail null) { return null; } return SaClientModel .newBuilder() .clientId(detail.getClientId()) .clientSecret(detail.getClientSecret()) .allowUrl(detail.getAllowUrls()) // 允许的回调地址多个用逗号隔开 .contractScope(detail.getContractScope()) .build(); }) // 自定义授权页面的代码 .setConfirmPageHtml((clientId, scope) - { // 这里可以返回一个自定义的HTML字符串例如Thymeleaf模板渲染的结果 return h1请确认授权/h1p客户端 clientId /pp权限范围 scope /p form method\post\button type\submit\确认授权/button/form; }); } /** * 注册 Sa-Token 的全局过滤器用于拦截并处理OAuth2请求 */ Bean public SaServletFilter getSaServletFilter() { return new SaServletFilter() .addInclude(/oauth2/*) // 拦截所有oauth2开头的请求 .setAuth(obj - { // 此处可以写一些预处理逻辑例如日志记录 }); } }实操心得setConfirmPageHtml这个配置非常有用。默认的授权确认页很简陋你可以在这里集成公司的UI组件库做一个风格统一的授权页。我曾在这里直接返回一个Vue组件的HTML通过Nginx代理静态资源实现了完全自定义的漂亮界面。3.3 用户登录与授权端点暴露认证中心需要提供标准的OAuth2端点。Sa-Token已经内置了这些端点我们只需要提供一个用户登录的接口即可。RestController RequestMapping(/oauth2) public class OAuth2ServerController { /** * 用户登录接口提供给认证中心自己的登录页使用 */ PostMapping(/doLogin) public SaResult doLogin(RequestParam String username, RequestParam String password) { // 1. 模拟从数据库查询用户信息生产环境需替换为真实查询 if(!zhang.equals(username) || !123456.equals(password)) { return SaResult.error(账号或密码错误); } // 2. 会话登录Sa-Token核心登录方法 StpUtil.login(10001); // 10001 是模拟的用户ID // 3. 返回登录成功信息及Token return SaResult.data(StpUtil.getTokenInfo()); } /** * 用户信息接口资源服务器校验令牌后调用此接口获取用户详情 */ GetMapping(/userinfo) public SaResult userinfo() { // 1. 获取当前登录用户ID (从Token中解析Sa-Token自动完成) Object userId StpUtil.getLoginId(); // 2. 模拟查询用户信息生产环境从数据库或缓存查 MapString, Object user new HashMap(); user.put(id, userId); user.put(name, 张三); user.put(avatar, https://xxx.com/avatar.png); user.put(perms, Arrays.asList(user.add, user.delete)); // 用户权限列表 return SaResult.data(user); } }注意StpUtil.login(id)是Sa-Token的核心登录方法它会在Redis中创建一个以这个id为key的Token令牌。这个令牌就是后续OAuth2流程中“用户已登录”状态的凭证。/userinfo端点是一个标准的userinfo端点资源服务器拿到访问令牌后可以调用此端点获取用户的详细信息。4. 客户端与资源服务器集成实战现在我们来配置需要接入SSO的业务服务它同时作为OAuth2的客户端和资源服务器。4.1 客户端配置在业务服务的application.yml中配置sa-token: oauth2: client: # 客户端模式授权码 mode: code # 认证中心地址 auth-url: http://localhost:9000/oauth2/authorize # 获取Token的地址 token-url: http://localhost:9000/oauth2/token # 用户信息地址 userinfo-url: http://localhost:9000/oauth2/userinfo # 客户端id client-id: test-client # 客户端密钥 client-secret: test-secret # 回调地址必须和认证中心配置的allow-url之一完全匹配 redirect-url: http://localhost:8081/sso/callback4.2 核心控制器处理回调与登录状态客户端需要两个核心接口1. 跳转到认证中心登录2. 处理认证中心回调。RestController public class SsoClientController { /** * 首页判断当前是否在本系统登录 */ RequestMapping(/) public SaResult index() { if(StpUtil.isLogin()) { // 已登录从会话中获取用户信息 Object userId StpUtil.getLoginId(); return SaResult.data(已登录用户id: userId , 详细信息: StpUtil.getSession().get(user)); } else { // 未登录提供登录链接 String authUrl SaOAuth2Client.newAuthRequest() // 创建授权请求 .setClientId(test-client) .setRedirectUri(http://localhost:8081/sso/callback) .setResponseType(code) .setScope(userinfo) // 申请的权限范围 .buildQueryUrl(); // 构建完整的授权地址 return SaResult.data(未登录a href\ authUrl \点击登录/a); } } /** * 单点登录回调地址核心 */ RequestMapping(/sso/callback) public SaResult callback(String code, String state) { // 1. 用授权码换取访问令牌 SaOAuth2Client saOAuth2Client new SaOAuth2Client(test-client, test-secret); SaOAuth2Token token saOAuth2Client.getAccessTokenByCode(code, http://localhost:8081/sso/callback); // 2. 用访问令牌获取用户信息 MapString, Object userInfo saOAuth2Client.getUserinfo(token.getAccessToken()); // 3. 在本地系统进行登录关键步骤 // 通常使用userInfo中的唯一标识如uid作为本地登录id String localUserId sso_ userInfo.get(id); // 建议加前缀避免与本地用户ID冲突 StpUtil.login(localUserId); // 4. 将用户信息存入本地会话可选但推荐 StpUtil.getSession().set(user, userInfo); // 5. 重定向到首页或原始访问页面 return SaResult.data(登录成功).set(tokenInfo, token).set(userInfo, userInfo); } /** * 受保护的资源API示例 */ SaCheckLogin // Sa-Token注解检查是否登录未登录将抛出异常 GetMapping(/api/user/profile) public SaResult profile() { Object userId StpUtil.getLoginId(); MapString, Object user (MapString, Object) StpUtil.getSession().get(user); return SaResult.data(您的个人信息 user); } }4.3 全局异常处理与拦截器配置为了统一处理未登录、权限不足等情况需要配置全局异常处理器。RestControllerAdvice public class GlobalExceptionHandler { /** * 拦截所有未登录异常 */ ExceptionHandler(NotLoginException.class) public SaResult handlerNotLoginException(NotLoginException e) { // 根据异常类型细分提示 String message; switch (e.getType()) { case NotLoginException.NOT_TOKEN: message 未提供Token; break; case NotLoginException.INVALID_TOKEN: message Token无效; break; case NotLoginException.TOKEN_TIMEOUT: message Token已过期; break; case NotLoginException.BE_REPLACED: message 账号已在别处登录; break; case NotLoginException.KICK_OUT: message 已被强制下线; break; default: message 当前会话未登录; } // 返回401状态码和跳转登录的地址 return SaResult.error(message).setCode(401); } /** * 拦截所有权限异常 */ ExceptionHandler(NotPermissionException.class) public SaResult handlerNotPermissionException(NotPermissionException e) { return SaResult.error(无此权限 e.getPermission()); } }同时为了让SaCheckLogin等注解生效需要在配置类中注册拦截器。Configuration public class SaTokenConfigure implements WebMvcConfigurer { /** * 注册Sa-Token的注解拦截器打开注解式鉴权功能 */ Override public void addInterceptors(InterceptorRegistry registry) { // 注册注解拦截器并排除不需要拦截的路径 registry.addInterceptor(new SaAnnotationInterceptor()).addPathPatterns(/**); } }5. 深度排查八大常见问题与解决方案实录在实际部署和联调中我遇到了各种各样的问题。下面这个表格是我整理的“血泪史”希望能帮你快速排雷。问题现象可能原因排查步骤与解决方案1. 点击登录后回调地址报错invalid redirect_uri这是最常见的问题。回调地址未在认证中心的allow-url中配置或格式不匹配。1. 检查客户端redirect-url配置的完整性和精确性包括http/https、端口、路径。2. 检查认证中心sa-token.oauth2.client.[clientId].allow-url配置确保回调地址完全匹配其中之一。支持逗号分隔多个地址。3.生产环境注意如果经过Nginx代理客户端获取到的请求地址可能是内网地址需在Nginx或代码中正确设置X-Forwarded-Proto和X-Forwarded-Host头部。2. 授权码兑换令牌时失败提示invalid client客户端ID或密钥错误或者认证中心的ClientModel加载器如从数据库读返回了null。1. 核对客户端client-id和client-secret确保与认证中心注册信息完全一致注意大小写和空格。2. 在认证中心SaOAuth2Template.setClientModelLoader方法内加日志或断点确认是否能根据clientId正确查询到客户端信息。3. 检查Redis连接是否正常有时客户端信息会缓存到Redis。3. 登录成功但进入业务系统后依然显示未登录客户端回调接口中用SSO返回的用户信息进行StpUtil.login()时使用的key与业务系统其他接口校验登录状态时使用的key不一致或未持久化。1.核心确保StpUtil.login(id)中的id是唯一且稳定的通常使用SSO用户中心返回的uid或username。建议拼接前缀如sso_uid避免与本地用户ID冲突。2. 检查Redis配置。客户端的登录状态Token也存储在Redis中。确保客户端应用的Redis配置正确且与认证中心共用或互通同一个Redis服务/集群。3. 检查Cookie域。如果多个业务系统域名不同需要在SaTokenConfig中配置token-domain为父级域名如.company.com并确保is-read-cookie为true。4. 令牌过期后无法自动刷新默认的授权码模式Sa-Token客户端不会自动刷新令牌。需要手动处理TokenInvalidException。1. 在全局异常处理器中捕获TokenInvalidException。2. 在异常处理逻辑中检查是否存在刷新令牌refresh_token。3. 如果存在则调用认证中心的/oauth2/refresh接口需自行实现或使用SaOAuth2Client的refreshAccessToken方法获取新的访问令牌。4. 更新本地会话的Token并重试原请求或引导用户重新授权。这是一个进阶功能需要仔细设计流程。5. 跨域问题在回调时出现CORS错误认证中心的授权接口和令牌接口被前端直接调用但未配置CORS。1. 最彻底的解决方案不要从前端直接调用认证中心接口。所有OAuth2流程应通过后端代理或重定向完成。授权请求是302重定向令牌请求是后端服务间的调用天然避免CORS。2. 如果确有需要在认证中心通过CrossOrigin注解或WebMvcConfigurer配置CORS。务必严格限制Origin不要使用*。6. 集成Spring Security后Sa-Token注解失效Spring Security的过滤器链优先级高于Sa-Token可能拦截请求并返回403。1. 如果不需要Spring Security的登录认证功能可以考虑在SSO客户端项目中排除Spring Security依赖。2. 如果需要Spring Security做其他事情如方法级安全则需配置Spring Security忽略OAuth2回调路径和API路径.requestMatchers(/sso/callback, /api/**).permitAll()。3. 调整过滤器顺序非常复杂不推荐新手尝试。7. 高并发下登录状态混乱或踢人下线不生效Redis配置或Sa-Token配置不当导致会话覆盖或并发问题。1. 检查sa-token.is-concurrent和sa-token.is-share配置。is-concurrentfalse时新登录会踢掉旧登录。is-sharetrue时同一账号所有端共享一个Token。根据业务场景选择。2.检查Redis连接池配置。高并发下连接数不足会导致超时和状态不一致。适当调大spring.redis.lettuce.pool.max-active。3. 考虑使用Redisson代替Lettuce作为Sa-Token的Redis客户端其对分布式锁的支持更好。8. 日志里大量NotLoginException但用户感觉正常可能是爬虫、健康检查或前端静态资源请求触发了登录校验。1. 在注册Sa-Token拦截器时使用addPathPatterns和excludePathPatterns精确排除不需要鉴权的路径如/favicon.ico,/error,/actuator/health,/static/**等。2. 在前端避免在全局请求拦截器中无条件地携带Token访问所有接口。3. 使用SaIgnore注解标注不需要登录的控制器方法。6. 生产环境进阶配置与优化建议当系统从本地开发走向生产环境时以下几个方面的优化至关重要。6.1 安全性加固使用HTTPS绝对必须。OAuth2流程中的授权码、令牌都在网络传输使用HTTPS是防止中间人攻击的基础。为认证中心和所有客户端服务配置有效的SSL证书。客户端密钥管理不要将client-secret硬编码在配置文件中。使用环境变量、配置中心如Nacos、Apollo或云厂商的密钥管理服务。授权码与令牌有效期缩短授权码activity-timeout的有效期例如5分钟。访问令牌timeout可根据业务设置如2小时。同时一定要启用刷新令牌并为其设置较长的有效期如7天。PKCE扩展对于公共客户端如SPA单页应用强烈建议启用PKCE。Sa-Token OAuth2模块也支持PKCE需要在创建授权请求时设置code_challenge和code_challenge_method。6.2 性能与高可用Redis高可用会话和令牌存储强烈依赖Redis。生产环境必须使用Redis哨兵或集群模式避免单点故障。在sa-token配置中可以配置多个Redis节点。认证中心集群化认证中心本身是无状态的状态在Redis因此可以轻松水平扩展。通过Nginx等负载均衡器将请求分发到多个认证中心实例。JWT替代部分Redis查询虽然Sa-Token默认将Token与权限关系存Redis但可以考虑使用JWT格式的Token将一些基本声明如用户ID、过期时间编码在Token本身。资源服务器无需每次请求都查询认证中心或Redis只需验证签名即可。这需要自定义SaTokenTemplate的实现。6.3 监控与审计日志集中收集在认证中心和客户端的关键节点如登录成功/失败、令牌颁发/刷新、权限校验失败打上详细的日志并接入ELK或类似日志平台。审计日志记录所有重要的OAuth2事件包括谁用户、客户端、在什么时间、从哪里IP、做了什么操作授权、访问资源、结果如何。这对于安全事件追溯至关重要。健康检查与熔断客户端服务需要监控与认证中心的连接状态。如果认证中心不可用应有降级策略如使用本地缓存的黑白名单进行基本校验或直接拒绝服务并给出友好提示。7. 与Spring Cloud Gateway的集成方案在微服务架构中我们通常使用API网关如Spring Cloud Gateway作为统一入口。网关可以统一处理SSO逻辑让下游业务服务完全无感知。方案思路网关拦截所有请求检查请求中是否携带Token可从Cookie或Header获取。如果无Token重定向到认证中心登录。如果有Token网关作为客户端向认证中心校验Token有效性并获取用户基本信息。网关将用户ID等信息以请求头如X-User-Id的形式转发给下游业务服务。业务服务只需信任网关转发的头部信息即可无需再集成Sa-Token客户端模块。这种模式解耦了业务服务和认证逻辑业务服务变得更纯粹。实现此方案需要在Spring Cloud Gateway中编写自定义的全局过滤器核心是调用SaOAuth2Client的checkAccessToken或getUserinfo方法。这虽然增加了网关的复杂性但带来了架构上的清晰度是大型微服务系统的常见选择。整个集成过程从架构设计到细节调试考验的是对OAuth2协议流程的深刻理解和对Sa-Token组件特性的熟练运用。记住单点登录不仅仅是技术的拼接更是对用户体验和安全边界的一种设计。多动手测试善用日志排查这套组合拳一定能帮你构建出稳定可靠的统一身份认证体系。
