基于sa-token实现OAuth2.0单点登录系统

1. 为什么需要OAuth2.0单点登录系统想象一下这样的场景你公司内部有财务系统、CRM系统、OA系统等多个业务平台每个系统都需要单独登录。员工每天要记住多套账号密码频繁切换系统时还要反复登录。这不仅影响工作效率还存在密码管理混乱的安全隐患。这就是我们需要单点登录SSO系统的根本原因。而OAuth2.0协议的出现让单点登录的实现变得更加标准化和安全。它就像一张数字通行证用户只需在一个系统完成认证就能访问所有关联应用。作为开发者我们既希望享受OAuth2.0的标准优势又想要保持权限控制的灵活性——这正是sa-token框架的用武之地。我去年负责过一个电商中台项目需要对接微信、支付宝等第三方登录同时还要管理内部员工权限。当时尝试过几种方案最终选择sa-token整合OAuth2.0的方案实测下来开发效率提升明显。特别是sa-token的注解式权限控制让接口权限管理变得异常简单。2. 环境准备与基础配置2.1 项目依赖配置首先创建一个Spring Boot项目在pom.xml中添加关键依赖。这里要注意版本兼容性我推荐使用以下稳定版本组合!-- sa-token核心库 -- dependency groupIdcn.dev33/groupId artifactIdsa-token-spring-boot-starter/artifactId version1.34.0/version /dependency !-- OAuth2客户端支持 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-oauth2-client/artifactId /dependency !-- 用于处理HTTP请求 -- dependency groupIdorg.apache.httpcomponents/groupId artifactIdhttpclient/artifactId version4.5.13/version /dependency2.2 配置文件详解在application.yml中配置OAuth2客户端信息。以GitHub OAuth2为例spring: security: oauth2: client: registration: github: client-id: your-client-id client-secret: your-client-secret authorization-grant-type: authorization_code redirect-uri: {baseUrl}/login/oauth2/code/{registrationId} scope: user:email provider: github: authorization-uri: https://github.com/login/oauth/authorize token-uri: https://github.com/login/oauth/access_token user-info-uri: https://api.github.com/user这里有几个容易踩坑的点redirect-uri中的{baseUrl}需要与实际部署地址完全匹配包括http/httpsscope要根据实际需求申请过大的权限范围可能被拒绝生产环境一定要保护好client-secret建议使用配置中心加密存储3. 核心实现步骤3.1 OAuth2登录流程实现创建一个控制器处理OAuth2登录回调。这里分享一个经过实战检验的代码模板Controller public class OAuth2LoginController { GetMapping(/login/oauth2/code/{registrationId}) public String callback(PathVariable String registrationId, RequestParam String code, HttpServletRequest request) { // 1. 通过code换取access_token OAuth2AccessToken accessToken oAuth2Service.getAccessToken(registrationId, code); // 2. 获取用户信息 OAuth2User oauth2User oAuth2Service.getUserInfo(registrationId, accessToken); // 3. 转换为本地用户体系 UserDetail userDetail convertToLocalUser(oauth2User); // 4. 创建sa-token会话 StpUtil.login(userDetail.getId()); StpUtil.getSession().set(user, userDetail); return redirect:/home; } }3.2 令牌转换机制OAuth2返回的access_token与sa-token的token体系需要转换这是整合的关键点。我的经验是建立双令牌映射关系public class TokenConverter { // 维护OAuth2 token与sa-token的映射关系 private static final ConcurrentHashMapString, String tokenMap new ConcurrentHashMap(); public static String convertToSaToken(String oauth2Token) { String saToken StpUtil.createTokenValue(); tokenMap.put(saToken, oauth2Token); return saToken; } public static String getOAuth2Token(String saToken) { return tokenMap.get(saToken); } }这样设计的好处是对外暴露的是sa-token保持系统内部一致性需要调用第三方API时可以快速获取原始OAuth2 token两边token的生命周期可以独立管理4. 权限控制与会话管理4.1 细粒度权限控制sa-token最强大的特性之一就是简洁的权限控制。我们可以结合OAuth2的scope实现多层权限// 注解式权限控制示例 SaCheckPermission(order:query) GetMapping(/orders) public ListOrder queryOrders() { // 业务逻辑 } // 编程式权限检查 public void deleteOrder(Long orderId) { if(StpUtil.hasPermission(order:delete)) { orderService.delete(orderId); } else { throw new ApiException(无删除权限); } }在实际项目中我通常会建立权限码映射表将OAuth2的scope转换为系统内部的权限标识。例如GitHub的user:email scope可以对应我们系统的user:basic权限。4.2 分布式会话管理当系统需要横向扩展时会话管理是个挑战。sa-token提供了多种存储适配器我推荐使用Redis方案# application.yml配置 sa-token: token-name: satoken timeout: 1800 activity-timeout: -1 is-share: true token-style: uuid >SaCheckSafe PostMapping(/update-profile) public Result updateProfile() { // 敏感操作 }权限回收当用户修改密码或权限变更时要及时清理会话public void onPasswordChange(Long userId) { // 踢出该用户所有会话 StpUtil.kickout(userId); }日志审计记录所有关键操作SaCheckLogin PostMapping(/transfer) public Result transfer(Valid TransferDTO dto) { // 操作前记录 SaLogUtil.log(StpUtil.getLoginId(), 执行转账操作, dto.toString()); // 业务逻辑... }5.2 异常处理实践OAuth2流程中可能出现的异常需要特别处理。这里分享我的异常处理模板RestControllerAdvice public class OAuth2ExceptionHandler { ExceptionHandler(OAuth2AuthenticationException.class) public Result handleOAuth2Error(OAuth2AuthenticationException e) { String errorCode e.getError().getErrorCode(); if(access_denied.equals(errorCode)) { return Result.fail(403, 用户取消了授权); } return Result.fail(500, 认证服务异常); } ExceptionHandler(SaTokenException.class) public Result handleSaTokenError(SaTokenException e) { if(e.getCode() 11011) { return Result.fail(401, 请重新登录); } return Result.fail(401, e.getMessage()); } }这种分层处理方式能提供更友好的错误提示。记得在前端对接时要根据不同错误码设计相应的用户引导流程。6. 实战优化技巧经过多个项目的实践我总结了几条提升体验的优化技巧无感刷新令牌当sa-token快过期时自动刷新Override public void onExpired(String tokenValue) { String oauth2Token TokenConverter.getOAuth2Token(tokenValue); // 检查OAuth2 token是否仍有效 if(oauth2Service.isTokenValid(oauth2Token)) { // 创建新token String newToken StpUtil.createTokenValue(); TokenConverter.convertToSaToken(oauth2Token); // 返回给前端 response.setHeader(New-Token, newToken); } }多端适配针对PC和移动端使用不同的token策略sa-token: token-style: pc: uuid mobile: simple-uuid性能监控集成Micrometer监控认证性能Bean public MeterRegistryCustomizerMeterRegistry saTokenMetrics() { return registry - { registry.gauge(sa_token.active_sessions, StpUtil.getSessionCount()); }; }在最近的一个项目中通过这些优化将认证模块的吞吐量提升了40%特别是无感刷新机制大大改善了移动端用户体验。