Sa-Token SSO 平台中心跳转模式实战一处登录点击链接免登录进入所有子系统【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token本篇指南围绕 Sa-Token 官方文档 sso-home-jump.md 展开讲解如何把 SSO-Server 认证中心升级为「平台中心」用户只需在认证中心登录一次即可通过首页上的链接免登录跳转进入各个子系统。文章将完整覆盖home-route配置、跳转链接改造格式、HomeController完整实现并结合sa-token-sso插件源码与单元测试剖析「跳转即自动登录」背后的重定向处理原理帮助读者掌握这一常见的多系统门户场景落地方法。一、场景与核心难点平台中心模式的诉求在很多企业中多个业务系统希望共用一个入口门户用户从门户首页进入任意子系统时都不需要重复登录。此时可以把 SSO-Server 搭建成一个平台中心效果大致如下用户首先访问 SSO-Server平台中心在统一登录页完成登录登录成功后进入平台首页首页上展示各个子系统的入口链接用户点击某个子系统的链接浏览器跳转到对应子系统并且自动完成登录免登录通行。「加一个超链接跳到子系统」并不难难的是跳转的同时让用户自动登录上子系统——直接跳转会丢失登录态。核心解法是对链接进行改造借助 SSO 的授权接口在跳转过程中完成一次授权换票从而让子系统信任用户身份实现「平台中心一处登录所有子系统无障碍通行」。该功能的对接前提是 SSO-Server 已搭建完成相关步骤详见 搭建统一认证中心 SSO-Server。SSO 的三种对接模式模式一/二/三分别见 sso-type1.md、sso-type2.md、sso-type3.md。二、跳转链接的改造格式假设某个子系统的地址是http://sa-sso-client1.com:9003/直接跳转显然不会自动登录我们需要把它改造成如下形式的授权链接/sso/auth?clientsso-client3redirecthttp://sa-sso-client1.com:9003/sso/login?backhttp://sa-sso-client1.com:9003/即通用格式为/sso/auth?client{client标识}redirect${子系统首页}/sso/login?back${子系统首页}各参数含义参数作用说明/sso/authSSO-Server 统一授权地址由 SSO-Server 处理器处理负责鉴权与重定向client子系统在 Server 端的应用标识必须与 Server 端sa-token.sso-server.clients中配置的应用名一致例如sso-client3redirect授权成功后的回跳地址回跳到子系统的/sso/login接口由 Client 端用 ticket 换取登录态back登录完成后最终返回的页面通常是子系统的首页例如http://sa-sso-client1.com:9003/整条链路可以这样理解/sso/auth负责确认「用户已在平台中心登录」确认后带着client、redirect完成跳转子系统的/sso/login拿到 ticket 后完成本地登录再按back参数把用户带回子系统首页。于是用户点击一个链接就完成了「平台中心鉴权 → 子系统换票登录 → 进入首页」的全过程。三、配置home-route登录后的默认落地页平台中心模式下用户通常是直接访问平台地址进入登录页的而不是从某个 Client 重定向而来。此时/sso/auth请求中没有携带redirect参数SSO-Server 需要有一个「默认跳转地址」作为登录成功后的落地页这个地址就是home-route。3.1 yaml 风格# Sa-Token 配置 sa-token: # SSO-Server 配置 sso-server: # 主页路由在 /sso/auth 登录页不指定 redirect 参数时默认跳转的地址 home-route: /home3.2 properties 风格# 主页路由在 /sso/auth 登录页不指定 redirect 参数时默认跳转的地址 sa-token.sso-server.home-route: /home官方 Demo 中该配置位于 sa-token-demo-sso-server/src/main/resources/application.yml 的sa-token.sso-server节点下与ticket-timeout、clients等配置并列sa-token: sso-server: # Ticket有效期 (单位: 秒)默认五分钟 ticket-timeout: 300 # 主页路由在 /sso/auth 登录页不指定 redirect 参数时默认跳转的地址 home-route: /home ...从源码结构看homeRoute字段定义在配置类 SaSsoServerConfig.java 中是一个字符串类型的路由路径既可以配置相对路径如/home也可以配置完整 URL测试代码中使用了http://sso-server.com/indexSSO-Server 在登录成功后会直接对该值发起重定向。四、编写平台中心首页HomeController在 sso-server 中添加HomeController作为平台中心首页。核心逻辑是未登录先重定向到/sso/auth登录已登录则渲染出一组指向各子系统的授权链接。/** * SSO 平台中心模式示例跳连接进入子系统 */ RestController public class HomeController { // 平台化首页 RequestMapping({/, /home}) public Object index() { // 如果未登录则先去登录 if(!StpUtil.isLogin()) { return SaHolder.getResponse().redirect(/sso/auth); } // 拼接各个子系统的地址格式形如/sso/auth?clientxxxredirect${子系统首页}/sso/login?back${子系统首页} String link1 /sso/auth?clientsso-client3redirecthttp://sa-sso-client1.com:9003/sso/login?backhttp://sa-sso-client1.com:9003/; String link2 /sso/auth?clientsso-client3redirecthttp://sa-sso-client2.com:9003/sso/login?backhttp://sa-sso-client2.com:9003/; String link3 /sso/auth?clientsso-client3redirecthttp://sa-sso-client3.com:9003/sso/login?backhttp://sa-sso-client3.com:9003/; // 组织网页结构返回到前端 String title h2SSO 平台首页 (平台中心模式)/h2; String client1 pa href link1 target_blank 进入Client1系统 /a/p; String client2 pa href link2 target_blank 进入Client2系统 /a/p; String client3 pa href link3 target_blank 进入Client3系统 /a/p; return title client1 client2 client3; } }该控制器与文档示例完全一致的实现已存在于官方 Demo HomeController.java可直接对照学习。实现要点登录前置检查通过StpUtil.isLogin()判断平台中心会话是否已建立未登录时用SaHolder.getResponse().redirect(/sso/auth)强制先走统一登录链接拼接即授权首页上的每个链接都已经带上了client与redirect参数点击即触发一次 SSO 授权流程页面渲染示例直接用字符串拼接 HTML 返回实际项目中可替换为模板引擎如 Thymeleaf参见 SSO-Server 搭建文档中的依赖说明 sso-server.md。五、底层原理/sso/auth是如何完成跳转的「跳转即自动登录」的关键在 SSO-Server 对/sso/auth请求的处理逻辑。源码位于 SaSsoServerProcessor.java 的ssoAuth()方法处理过程分为两种情况情况 1平台中心尚未登录如果StpUtil判定当前会话未登录则直接返回登录视图notLoginView引导用户先登录代码逻辑为if( ! stpLogic.isLogin()) { return ssoServerTemplate.strategy.notLoginView.get(); }情况 2平台中心已登录开始跳转此时读取mode、redirect、client等参数构建最终重定向地址String redirectUrl SaSugar.get(() - { // 若 redirect 参数为空说明用户并不是从 client 重定向来的 // 而是直接访问的 http://sso-server.com/sso/auth 地址 // 此时需要跳转到配置的 homeRoute 路由上 // 若 homeRoute 也为空则没有明确的跳转地址了需要抛出异常 if(SaFoxUtil.isEmpty(redirect)) { if(SaFoxUtil.isEmpty(cfg.getHomeRoute())) { throw new SaSsoException(未指定 redirect 参数也未配置 homeRoute 路由无法完成重定向操作) .setCode(SaSsoErrorCode.CODE_30014); } return cfg.getHomeRoute(); } // 方式1直接重定向回Client端 (modesimple一般是模式一) if(mode.equals(SaSsoConsts.MODE_SIMPLE)) { ssoServerTemplate.checkRedirectUrl(client, redirect); return redirect; } else { // 方式2带着 ticket 参数重定向回Client端 (modeticket一般是模式二、三) String _redirectUrl ssoServerTemplate.buildRedirectUrl(client, redirect, stpLogic.getLoginId(), stpLogic.getTokenValue()); ... return _redirectUrl; } }); ssoServerTemplate.strategy.jumpToRedirectUrlNotice.run(redirectUrl); return res.redirect(redirectUrl);这段源码解释了平台中心模式的两个核心行为redirect为空时落到homeRoute直接访问/sso/auth无redirect参数时登录成功后跳转到home-route配置的地址——这正是「平台中心首页」能作为登录落地页的原因redirect非空时回跳子系统当链接带有redirect参数时平台首页点击进入子系统默认以 ticket 模式调用buildRedirectUrl(...)在redirect地址上追加ticket参数后重定向子系统拿到 ticket 即可换取登录态实现免登录进入。模式一同域、同 Redis下则可使用modesimple直接回跳无需 ticket。此外源码还做了防御性处理对redirect参数使用SaFoxUtil.decoderUrlIfEncoded(_redirect)进行二次解码兼容不同 Web 容器对 URL 参数的解码差异。边界情况既无 redirect 也无 homeRoute从源码与错误码定义 SaSsoErrorCode.java 可以看到若用户直接访问/sso/auth且既未携带redirect参数、也未配置homeRouteSSO-Server 将抛出CODE_30014异常未指定 redirect 参数也未配置 homeRoute 路由无法完成重定向操作。因此平台中心模式必须配置home-route否则无法确定登录成功后的默认落地页。测试用例佐证sa-token-sso插件的单元测试 SaSsoServerProcessorTest.java 对上述行为做了精确验证ssoAuth_loggedInEmptyRedirectNoHome_throws30014已登录、无redirect、无homeRoute时抛出30014异常ssoAuth_loggedInEmptyRedirectHasHome_redirectsHome已登录、无redirect、但配置了homeRoutehttp://sso-server.com/index时重定向地址即为该路由。这两个用例从测试层面印证了home-route配置项在「无 redirect 兜底跳转」场景中的决定性作用可作为平台中心模式行为正确性的回归验证参考。六、测试访问验证平台中心跳转效果完成以上配置与编码后按如下步骤验证启动 SSO-Server 项目访问平台中心地址http://sa-sso-server.com:9000首次访问时由于尚未登录会被自动重定向到/sso/auth统一登录页使用账号密码登录后浏览器跳转到平台中心首页即home-route配置的/home依次点击「进入 Client1 / Client2 / Client3 系统」三个链接即可在跳转的同时自动登录上对应子系统。联调提示示例中的sa-sso-client1.com等域名需要在本地 hosts 文件中配置解析才能访问SSO-Server 启动时会打印相关提示。Demo 项目中各 Client 端默认测试账号密码为sa / 123456详见 sso-server.md。七、生产环境落地建议client标识要一致首页链接中的client参数必须与 Server 端sa-token.sso-server.clients下配置的应用标识完全一致否则授权校验会失败allow-url不要使用通配符官方 Demo 为了方便测试将allow-url配置为*生产环境务必配置为精确的回调 URL防止被恶意利用详细说明见 sso-server.mdhome-route建议配置为相对路径如/home避免环境迁移时因域名变更导致硬编码失效如需跨域场景也可配置完整 URLSSO 模式选择平台中心跳转本质上是「SSO-Server 发起授权、Client 端换票登录」具体走模式一同域、同 Redis、模式二跨域、同 Redis还是模式三跨域、跨 Redis由各子系统的对接方式决定可分别参考 sso-type1.md、sso-type2.md、sso-type3.md安全提示secret-key是 Client 与 Server 之间接口调用的签名秘钥生产环境务必使用强随机值并确保is-check-sign参数签名校验保持开启。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考