XXL-SSO 分布式单点登录框架

XXL-SSO 分布式单点登录框架使用手册

🎯 项目概述

XXL-SSO是一个分布式单点登录框架，让您只需一次登录即可访问所有可信应用。该框架具有"轻量级、高可扩展、进度可控"等特性，支持登录认证、权限认证、分布式会话认证、单点登出等多种功能。

官方地址：https://www.xuxueli.com/xxl-sso/

📋 版本信息

•当前版本 ：2.3.2-SNAPSHOT•开发语言 ：Java•核心依赖 ：Spring Boot 4.0.1, Spring 7.0.2•许可证：GPL v3

🏗️ 架构设计

核心组件

1.xxl-sso-core - 核心认证模块2.xxl-sso-server - 认证中心服务器3.xxl-sso-samples - 示例应用集合

认证模式支持

•✅ Web端登录 - 传统浏览器登录•✅ Native端登录 - 移动端APP登录•✅ CAS集成 - 支持CAS协议•✅ 过滤器模式 - 基于Filter的集成•✅ 拦截器模式 - 基于Interceptor的集成

🚀 快速开始

1. 环境要求

•JDK 17+•Maven 3.6+•Redis 6.0+•MySQL 8.0+（可选）

2. 服务端部署

配置文件 ：xxl-sso-server/src/main/resources/application.properties

properties 复制代码

# 服务端口server.port=8080server.servlet.context-path=/xxl-sso-server# 令牌配置xxl-sso.token.key=xxl_sso_tokenxxl-sso.token.timeout=604800000# Redis配置xxl-sso.store.redis.nodes=127.0.0.1:6379xxl-sso.store.redis.user=xxl-sso.store.redis.password=xxl-sso.store.redis.keyprefix=xxl_sso_user

启动命令：

bash 复制代码

cd xxl-sso-servermvn spring-boot:run

3. 客户端集成

Web应用集成（Filter模式）

Maven依赖：

xml 复制代码

<dependency><groupId>com.xuxueli</groupId><artifactId>xxl-sso-core</artifactId><version>2.3.2-SNAPSHOT</version></dependency>

配置文件 ：application.properties

properties 复制代码

# 服务端地址xxl.sso.server.address=http://localhost:8080/xxl-sso-server# 令牌配置xxl-sso.token.key=xxl_sso_tokenxxl-sso.token.timeout=604800000# Redis配置xxl-sso.store.redis.nodes=127.0.0.1:6379xxl-sso.store.redis.keyprefix=xxl_sso_user# 排除路径xxl-sso.client.excluded.paths=/weblogin/*,/static/**xxl-sso.client.login.path=/weblogin/login

Filter配置：

java 复制代码

@BeanpublicFilterRegistrationBean<XxlSsoWebFilter> xxlSsoWebFilter(){FilterRegistrationBean<XxlSsoWebFilter> registration =newFilterRegistrationBean<>();    registration.setFilter(newXxlSsoWebFilter());    registration.addUrlPatterns("/*");    registration.setName("XxlSsoWebFilter");return registration;}

Spring MVC集成（Interceptor模式）

java 复制代码

@ConfigurationpublicclassWebMvcConfigimplementsWebMvcConfigurer{@Overridepublicvoid addInterceptors(InterceptorRegistry registry){        registry.addInterceptor(newXxlSsoWebInterceptor()).addPathPatterns("/**").excludePathPatterns("/weblogin/*","/static/**");}}

🔧 核心功能

1. 单点登录流程

sequenceDiagram participant Useras用户 participant Clientas客户端应用 participant SSO as SSO认证中心 participant RedisasRedis缓存User->>Client:访问受保护资源Client->>SSO:重定向到登录页 SSO->>User:显示登录表单User->>SSO:提交用户名密码 SSO->>SSO:验证用户信息 SSO->>Redis:存储用户会话 SSO->>Client:返回授权码Client->>SSO:获取访问令牌 SSO->>Client:返回用户信息Client->>User:访问受保护资源

2. 用户信息获取

在Controller中获取登录用户信息：

java 复制代码

@RequestMapping("/userInfo")publicString userInfo(HttpServletRequest request){XxlSsoUser xxlUser =(XxlSsoUser) request.getAttribute(XXL_SSO_USER);if(xxlUser !=){String username = xxlUser.getUsername();String userid = xxlUser.getUserid();// 处理用户信息}return"userInfo";}

3. 单点登出

java 复制代码

@RequestMapping("/logout")publicString logout(HttpServletRequest request,HttpServletResponse response){// 清除本地会话    request.getSession().invalidate();// 调用SSO登出接口String logoutUrl ="http://localhost:8080/xxl-sso-server/logout";return"redirect:"+ logoutUrl;}

⚙️ 高级配置

1. Redis集群配置

properties 复制代码

# Redis集群配置xxl-sso.store.redis.nodes=192.168.1.100:6379,192.168.1.101:6379,192.168.1.102:6379xxl-sso.store.redis.user=adminxxl-sso.store.redis.password=your_passwordxxl-sso.store.redis.keyprefix=xxl_sso_user

2. 令牌安全配置

properties 复制代码

# 令牌传输密钥xxl-sso.token.key=your_custom_token_key# 令牌超时时间（毫秒）xxl-sso.token.timeout=3600000# 1小时

3. 排除路径配置

properties 复制代码

# 排除不需要认证的路径xxl-sso.client.excluded.paths=/weblogin/*,/static/**,/api/public/*

📊 性能优化

1. Redis连接池优化

properties 复制代码

# Redis连接池配置spring.redis.lettuce.pool.max-active=20spring.redis.lettuce.pool.max-idle=10spring.redis.lettuce.pool.min-idle=5spring.redis.lettuce.pool.max-wait=5000ms

2. 会话缓存策略

•默认策略 ：Redis存储，分布式共享•本地缓存 ：可结合Caffeine等本地缓存提升性能•缓存过期：配置合理的TTL避免内存泄漏

🛡️ 安全建议

1.令牌密钥：使用强随机字符串作为token.key2.HTTPS传输：生产环境必须使用HTTPS3.Redis安全：启用Redis密码认证4.路径排除：谨慎配置排除路径，避免安全漏洞5.会话超时：设置合理的token超时时间

🔍 监控与排查

1. 日志配置

properties 复制代码

# 开启SSO调试日志logging.level.com.xxl.sso=DEBUG

2. 常见问题排查

问题1：无法获取用户信息

•检查Redis连接状态•验证token.key配置是否一致•确认用户会话是否过期

问题2：登录循环跳转

•检查排除路径配置•验证SSO服务器地址配置•查看Filter/Interceptor注册顺序

📚 示例项目

项目提供了丰富的示例代码：

1.xxl-sso-sample-interceptor-web - Web拦截器模式2.xxl-sso-sample-interceptor-native - Native拦截器模式3.xxl-sso-sample-interceptor-cas - CAS集成模式4.*xxl-sso-sample-filter-系列 - 过滤器模式示例

🤝 技术支持

•官方文档 ：https://www.xuxueli.com/xxl-sso/•**GitHub仓库** ：https://github.com/xuxueli/xxl-sso•**问题反馈** ：https://github.com/xuxueli/xxl-sso/issues•**社区交流**：https://www.xuxueli.com/page/community.html

📄 开源协议

本项目采用 GPL v3 开源协议，完全免费开源。

💡 使用建议

1.开发环境：先运行官方示例，熟悉流程后再集成到自己的项目2.生产部署：建议使用Redis集群确保高可用性3.定制开发：基于xxl-sso-core模块进行二次开发4.版本升级：关注官方更新，及时升级到最新版本

通过XXL-SSO框架，您可以快速构建稳定可靠的分布式单点登录系统，提升用户体验和系统安全性。

XXL-SSO 分布式单点登录框架