当前位置：首页 > news >正文

分布式单点登录框架XXL-SSO：从架构到实践的全方位解析

news 2026/5/26 21:20:00

分布式单点登录框架XXL-SSO：从架构到实践的全方位解析

分布式单点登录框架XXL-SSO是一款轻量级、高扩展、渐进式的单点登录解决方案，支持登录认证、权限认证、角色认证、分布式会话认证等多种功能，已广泛应用于电商、O2O、CRM等业务场景。本文将从核心特性、架构设计到快速接入，为您全面解析XXL-SSO的使用方法和技术原理。

一、为什么选择XXL-SSO？三大核心优势解析 ✨

XXL-SSO作为一款成熟的开源单点登录框架，具备以下显著优势：

1.1 轻量级架构，零依赖部署 🚀

框架设计遵循"轻量级"理念，对第三方组件和部署环境零依赖，仅需JDK17+即可运行。核心模块xxl-sso-core体积小巧，接入成本低，适合各类系统快速集成。

1.2 多场景适配，渐进式集成 🔄

支持三种登录模式，满足不同业务场景需求：

Web常规登录：适用于单体系统，登录凭证存储在公共域名Cookie中
Native登录：针对移动端、前后端分离场景，支持无Cookie环境
CAS单点登录：解决多系统跨域统一认证问题，需部署独立认证中心

1.3 高扩展性设计，灵活定制 🔧

采用模块化抽象设计，关键组件支持自定义扩展：

LoginStore：登录态存储组件，提供Redis、本地缓存等实现
Auth拦截器：支持Filter(Servlet)和Interceptor(Spring)两种集成方式
LoginInfo模型：统一用户模型，支持扩展自定义属性

二、XXL-SSO架构深度剖析 🏗️

2.1 整体架构设计

XXL-SSO采用分层架构设计，主要包含应用层、认证层和存储层：

XXL-SSO架构图

应用层：支持浏览器、移动端、前端Native、PC客户端等多端接入
认证层：提供CasAuth、WebAuth、NativeAuth三种认证方式
存储层：通过LoginStore组件实现登录态持久化，支持Redis、本地存储等

2.2 核心登录流程解析

Web常规登录流程

适用于单体Web系统，基于Cookie实现登录态共享：

Web常规登录流程

核心步骤：

用户请求受限资源，未登录时重定向至登录页
提交账号密码，服务端验证后生成LoginInfo和token
token写入公共域名Cookie，LoginInfo存储至LoginStore
后续请求通过Cookie携带token，服务端验证通过后放行

CAS单点登录流程

解决跨域系统统一认证问题，需独立部署CAS认证中心：

CAS登录流程

核心优势：

跨域认证：支持不同域名系统间的登录态共享
单点注销：一处注销，所有关联系统同时登出
高可用设计：认证中心支持集群部署，登录态通过LoginStore共享

Native登录流程

适用于移动端、前后端分离等无Cookie场景：

Native登录流程

实现特点：

基于token认证，客户端自行维护登录凭证
通过Header传递token，不依赖Cookie
天然支持多端登录，登录态全局共享

三、快速上手：3步集成XXL-SSO 🏃‍♂️

3.1 环境准备与项目获取

环境要求：

JDK 17+
Maven 3+
Redis 7.4+（可选，使用RedisLoginStore时需要）

获取源码：

git clone https://gitcode.com/gh_mirrors/xx/xxl-sso

项目结构说明：

xxl-sso/ ├── xxl-sso-core/ # 核心依赖模块 ├── xxl-sso-server/ # CAS认证中心（仅CAS模式需要） └── xxl-sso-samples/ # 各类接入示例 ├── xxl-sso-sample-interceptor-web/ # Web常规登录示例 ├── xxl-sso-sample-interceptor-native/ # Native登录示例 └── xxl-sso-sample-interceptor-cas/ # CAS单点登录示例

3.2 Web常规登录快速接入

以Spring Boot应用为例，只需三步即可完成集成：

第一步：引入Maven依赖

<dependency> <groupId>com.xuxueli</groupId> <artifactId>xxl-sso-core</artifactId> <version>{最新版本}</version> </dependency>

第二步：配置XXL-SSO

创建配置类XxlSsoConfig：

@Configuration public class XxlSsoConfig implements WebMvcConfigurer { @Value("${xxl-sso.token.key}") private String tokenKey; @Value("${xxl-sso.token.timeout}") private long tokenTimeout; @Bean(initMethod = "start", destroyMethod = "stop") public XxlSsoBootstrap xxlSsoBootstrap() { XxlSsoBootstrap bootstrap = new XxlSsoBootstrap(); bootstrap.setLoginStore(new RedisLoginStore( "127.0.0.1:6379", "", "", "xxl_sso_user")); bootstrap.setTokenKey(tokenKey); bootstrap.setTokenTimeout(tokenTimeout); return bootstrap; } @Override public void addInterceptors(InterceptorRegistry registry) { XxlSsoWebInterceptor interceptor = new XxlSsoWebInterceptor( "/weblogin/*,/static/**", "/weblogin/login"); registry.addInterceptor(interceptor).addPathPatterns("/**"); } }

第三步：使用注解保护接口

@RestController public class IndexController { // 需要登录 @RequestMapping("/test1") @XxlSso public String test1(HttpServletRequest request) { Response<LoginInfo> loginInfo = XxlSsoHelper.loginCheckWithAttr(request); return "登录用户：" + loginInfo.getData().getUserName(); } // 需要特定权限 @RequestMapping("/test2") @XxlSso(permission = "user:query") public String test2() { return "拥有user:query权限"; } // 需要特定角色 @RequestMapping("/test3") @XxlSso(role = "admin") public String test3() { return "拥有admin角色"; } }

3.3 验证登录效果

启动应用后访问受保护接口，将自动跳转至登录页：

XXL-SSO登录页面

登录成功后可访问受保护资源，系统主页如下：

XXL-SSO系统主页

四、核心功能与最佳实践 💡

4.1 多维度认证控制

XXL-SSO提供三种认证方式，满足不同场景需求：

登录认证：验证用户身份，确认"你是谁"
权限认证：验证用户是否具备特定操作权限
角色认证：验证用户是否属于特定角色

使用注解即可轻松实现：

// 仅需登录 @XxlSso // 不需要登录 @XxlSso(login = false) // 需要特定权限 @XxlSso(permission = "order:create") // 需要特定角色 @XxlSso(role = "manager")

4.2 登录态管理

XXL-SSO提供完善的登录态管理机制：

自动延期：登录态有效期过半时自动顺延
记住密码：勾选时延长登录态有效期，未勾选则关闭浏览器失效
强制注销：支持通过API主动注销指定用户登录态

// 登录 Response<String> loginResult = XxlSsoHelper.login(loginInfo); String token = loginResult.getData(); // 注销 XxlSsoHelper.logout(token); // 检查登录状态 Response<LoginInfo> result = XxlSsoHelper.loginCheck(token);