于 2018 年初, 在 GitHub 上创建 XXL-SSO 项目仓库并提交第一个 commit, 随之进行系统结构设计, UI 选型, 交互设计......
于 2018-12-05,XXL-SSO 参与 "2018 年度最受欢迎中国开源软件 https://www.oschina.net/project/top_cn_2018?sort=1" 评比, 在当时已录入的一万多个国产开源项目中角逐, 最终排名第 55 名.
于 2019-01-23,XXL-SSO 被评选上榜 "2018 年度新增开源软件排行榜之国产 TOP 50" 评比, 排名第 8 名.
至今, XXL-SSO 已接入多家公司的线上产品线, 接入场景如电商业务, O2O 业务和核心中间件配置动态化等, 截止 2018-03-15 为止, XXL-SSO 已接入的公司包括不限于:
湖南创发科技
深圳龙华科技有限公司
摩根国际
印记云
一, 简介
1.1 概述
XXL-SSO 是一个分布式单点登录框架. 只需要登录一次就可以访问所有相互信任的应用系统.
拥有 "轻量级, 分布式, 跨域, Cookie+Token 均支持, web+APP 均支持" 等特性. 现已开放源代码, 可以做到开箱即用.
1.2 特性
1, 简洁: API 直观简洁, 可快速上手;
2, 轻量级: 环境依赖小, 部署与接入成本较低;
3, 单点登录: 只需要登录一次就可以访问所有相互信任的应用系统.
4, 分布式: 接入 SSO 认证中心的应用, 支持分布式部署;
5,HA:Server 端与 Client 端, 均支持集群部署, 提高系统可用性;
6, 跨域: 支持跨域应用接入 SSO 认证中心;
7,Cookie+Token 均支持: 支持基于 Cookie 和基于 Token 两种接入方式, 并均提供 Sample 项目;
8,Web+App 均支持: 支持 Web 和 App 接入;
9, 实时性: 系统登陆, 注销状态, 全部 Server 与 Client 端实时共享;
10,CS 结构: 基于 CS 结构, 包括 Server"认证中心" 与 Client"受保护应用";
11, 记住密码: 未记住密码时, 关闭浏览器则登录态失效; 记住密码时, 支持登录态自动延期, 在自定义延期时间的基础上, 原则上可以无限延期;
12, 路径排除: 支持自定义多个排除路径, 支持 Ant 表达式. 用于排除 SSO 客户端不需要过滤的路径;
1.3 下载
文档地址
中文文档 http://www.xuxueli.com/xxl-sso/
源码仓库地址
技术交流
社区交流 http://www.xuxueli.com/page/community.html
1.4 环境
- JDK:1.7+********
- Redis:4.0+
- MySQL:5.6+
二, 快速入门(基于 Cookie)
2.1 系统数据库初始化
2.2 源码编译
- xxl-sso-server: 中央认证服务, 支持集群;
- xxl-sso-core:Client 端依赖;
- xxl-sso-samples: 单点登陆 Client 端接入示例项目;
- xxl-sso-Web-sample-springboot: 基于 Cookie 接入方式, 供用户浏览器访问, springboot 版本
- xxl-sso-token-sample-springboot: 基于 Token 接入方式, 常用于无法使用 Cookie 的场景使用, 如 App,Cookie 被禁用等, springboot 版本
2.3 部署 "认证中心(SSO Server)"
项目名: xxl-sso-server
配置说明
配置文件位置: application.properties
- ......
- // Redis 地址: 如 "{ip}","{ip}:{port}","{redis/rediss}://xxl-sso:{password}@{ip}:{port:6379}/{db}"; 多地址逗号分隔
- xxl.sso.Redis.address=Redis://127.0.0.1:6379
- // 登录态有效期窗口, 默认 24H, 当登录态有效期窗口过半时, 自动顺延一个周期;
- xxl.sso.Redis.expire.minite=1440
Redis 密码配置
在 xxl-sso-core 项目中 com.xxl.sso.core.util 包下的 JedisUtil 类中大约 85 行设置密码, 如若 Redis 没有设置密码, 则不需要配置此处.
- for (int i = 0; i <addressArr.length; i++) {
- JedisShardInfo jedisShardInfo = new JedisShardInfo(addressArr[i]);
- jedisShardInfo.setPassword("******");# 添加密码
- jedisShardInfos.add(jedisShardInfo);
- }
2.4 部署 "单点登陆 Client 端接入示例项目"
项目名: xxl-sso-Web-sample-springboot
maven 依赖
- <dependency>
- <groupId>com.xuxueli</groupId>
- <artifactId>xxl-sso-core</artifactId>
- <version>${最新稳定版}</version>
- </dependency>
配置 XxlSsoFilter
参考代码: com.xxl.sso.sample.config.XxlSsoConfig
- @Bean
- public FilterRegistrationBean xxlSsoFilterRegistration() {
- // xxl-sso, Redis init
- JedisUtil.init(xxlSsoRedisAddress);
- // xxl-sso, filter init
- FilterRegistrationBean registration = new FilterRegistrationBean();
- registration.setName("XxlSsoWebFilter");
- registration.setOrder(1);
- registration.addUrlPatterns("/*");
- registration.setFilter(new XxlSsoWebFilter());
- registration.addInitParameter(Conf.SSO_SERVER, xxlSsoServer);
- registration.addInitParameter(Conf.SSO_LOGOUT_PATH, xxlSsoLogoutPath);
- return registration;
- }
配置说明
配置文件位置: application.properties
- ......
- ### xxl-sso (CLient 端 SSO 配置)
- ##### SSO Server 认证中心地址(推荐以域名方式配置认证中心, 本机可参考章节 "2.5" 修改 host 文件配置域名指向)
- xxl.sso.server=http://xxlssoserver.com:8080/xxl-sso-server
- ##### 注销登陆 path, 值为 Client 端应用的相对路径
- xxl.sso.logout.path=/logout
- ##### 路径排除 Path, 允许设置多个, 且支持 Ant 表达式. 用于排除 SSO 客户端不需要过滤的路径
- xxl-sso.excluded.paths=
- ### Redis // Redis address, like "{ip}","{ip}:{port}","{redis/rediss}://xxl-sso:{password}@{ip}:{port:6379}/{db}";Multiple "," separated
- xxl.sso.Redis.address=Redis://xxl-sso:password@127.0.0.1:6379/0
路径过滤: 在 xxl-sso-core 项目中 com.xxl.sso.core.filer 包下的 XxlSsoWebFilter 类中大约 54 行
- // excluded path check
- if (excludedPaths!=null && excludedPaths.trim().length()>0) {
- for (String excludedPath:excludedPaths.split(",")) {
- String uriPattern = excludedPath.trim();
- // 支持 ANT 表达式
- if (antPathMatcher.match(uriPattern, servletPath)) {
- // excluded path, allow
- chain.doFilter(request, response);
- return;
- }
- }
- }
判断登录重定向: 在 xxl-sso-core 项目中 com.xxl.sso.core.filer 包下的 XxlSsoWebFilter 类中大约 82 行
- // valid login fail
- if (xxlUser == null) {
- String header = req.getHeader("content-type");
- boolean isJson= header!=null && header.contains("json");
- if (isJson) {
- // JSON msg
- res.setContentType("application/json;charset=utf-8");
- res.getWriter().println("{\"code\":"+Conf.SSO_LOGIN_FAIL_RESULT.getCode()+", \"msg\":\""+ Conf.SSO_LOGIN_FAIL_RESULT.getMsg() +"\"}");
- return;
- } else {
- // total link
- String link = req.getRequestURL().toString();
- // redirect logout
- String loginPageUrl = ssoServer.concat(Conf.SSO_LOGIN)
- + "?" + Conf.REDIRECT_URL + "=" + link;
- res.sendRedirect(loginPageUrl);
- return;
- }
- }
2.5 验证
环境准备: 启动 Redis, 初始化 MySQL 表数据;
修改 Host 文件: 域名方式访问认证中心, 模拟跨域与线上真实环境
- ### 在 host 文件中添加以下内容 0
- 127.0.0.1 xxlssoserver.com
- 127.0.0.1 xxlssoclient1.com
- 127.0.0.1 xxlssoclient2.com
分别运行 "xxl-sso-server" 与 "xxl-sso-web-sample-springboot"
1,SSO 认证中心地址:
http://xxlssoserver.com:8080/xxl-sso-server
2,Client01 应用地址:
http://xxlssoclient1.com:8081/xxl-sso-web-sample-springboot/
3,Client02 应用地址:
http://xxlssoclient2.com:8081/xxl-sso-web-sample-springboot/
SSO 登录 / 注销流程验证
正常情况下, 登录流程如下:
1, 访问 "Client01 应用地址" , 将会自动 redirect 到 "SSO 认证中心地址" 登录界面;
2, 成功登录后, 将会自动 redirect 返回到 "Client01 应用地址", 并切换为已登录状态;
3, 此时, 访问 "Client02 应用地址", 不需登陆将会自动切换为已登录状态;
正常情况下, 注销流程如下:
1, 访问 "Client01 应用地址" 配置的 "注销登陆 path", 将会自动 redirect 到 "SSO 认证中心地址" 并自动注销登陆状态;
2, 此时, 访问 "Client02 应用地址", 也将会自动注销登陆状态;
````
2.5 登录源码分析
- @RequestMapping("/doLogin")
- public String doLogin(HttpServletRequest request,
- HttpServletResponse response,
- RedirectAttributes redirectAttributes,
- String username,
- String password,
- String ifRemember) {
- boolean ifRem = (ifRemember!=null&&"on".equals(ifRemember))?true:false;// 判断是否记住密码
- // valid login
- ReturnT<UserInfo> result = userService.findUser(username, password);// 校验密码是否正确
- if (result.getCode() != ReturnT.SUCCESS_CODE) {
- redirectAttributes.addAttribute("errorMsg", result.getMsg());
- redirectAttributes.addAttribute(Conf.REDIRECT_URL, request.getParameter(Conf.REDIRECT_URL));
- return "redirect:/login";
- }
- // 1,make xxl-sso user 根据不同规则设置用户信息
- XxlSsoUser xxlUser = new XxlSsoUser();
- xxlUser.setUserid(String.valueOf(result.getData().getUserid()));
- xxlUser.setUsername(result.getData().getUsername());
- xxlUser.setVersion(UUID.randomUUID().toString().replaceAll("-", ""));
- xxlUser.setExpireMinute(SsoLoginStore.getRedisExpireMinute());
- xxlUser.setExpireFreshTime(System.currentTimeMillis());
- // 2,make session id 根据用户信息生成 sessionId
- String sessionId = SsoSessionIdHelper.makeSessionId(xxlUser);
- // 3,login, store storeKey + cookie sessionId 将 sessionId & 用户信息存入 Reids
- SsoWebLoginHelper.login(response, sessionId, xxlUser, ifRem);
- // 4,return, redirect sessionId 重定向到子系统(并传递 xxl_sso_sessionid)
- String redirectUrl = request.getParameter(Conf.REDIRECT_URL);
- if (redirectUrl!=null && redirectUrl.trim().length()>0) {
- String redirectUrlFinal = redirectUrl + "?" + Conf.SSO_SESSIONID + "=" + sessionId;
- return "redirect:" + redirectUrlFinal;
- } else {
- return "redirect:/";
- }
- }
校验密码是否正确
- @Override
- public ReturnT<UserInfo> findUser(String username, String password) {
- if (username==null || username.trim().length()==0) {
- return new ReturnT<UserInfo>(ReturnT.FAIL_CODE, "Please input username.");
- }
- if (password==null || password.trim().length()==0) {
- return new ReturnT<UserInfo>(ReturnT.FAIL_CODE, "Please input password.");
- }
- // mock user
- for (UserInfo mockUser: mockUserList) {
- if (mockUser.getUsername().equals(username) && mockUser.getPassword().equals(password)) {
- return new ReturnT<UserInfo>(mockUser);
- }
- }
- return new ReturnT<UserInfo>(ReturnT.FAIL_CODE, "username or password is invalid.");
- }
根据用户信息生成 sessionId
- public static String makeSessionId(XxlSsoUser xxlSsoUser){
- String sessionId = xxlSsoUser.getUserid().concat("_").concat(xxlSsoUser.getVersion());
- return sessionId;
- }
将 sessionId & 用户信息存入 Reids
- public static void login(HttpServletResponse response,
- String sessionId,
- XxlSsoUser xxlUser,
- boolean ifRemember) {
- String storeKey = SsoSessionIdHelper.parseStoreKey(sessionId);
- if (storeKey == null) {
- throw new RuntimeException("parseStoreKey Fail, sessionId:" + sessionId);
- }
- SsoLoginStore.put(storeKey, xxlUser);
- CookieUtil.set(response, Conf.SSO_SESSIONID, sessionId, ifRemember);// 在认证授权系统下存放对应 cookie 信息
- }
- public static XxlSsoUser loginCheck(HttpServletRequest request, HttpServletResponse response){
- String cookieSessionId = CookieUtil.getValue(request, Conf.SSO_SESSIONID);
- // cookie user
- XxlSsoUser xxlUser = SsoTokenLoginHelper.loginCheck(cookieSessionId);
- if (xxlUser != null) {
- return xxlUser;
- }
- // redirect user
- // remove old cookie
- SsoWebLoginHelper.removeSessionIdByCookie(request, response);
- // set new cookie
- String paramSessionId = request.getParameter(Conf.SSO_SESSIONID);
- xxlUser = SsoTokenLoginHelper.loginCheck(paramSessionId);
- if (xxlUser != null) {
- CookieUtil.set(response, Conf.SSO_SESSIONID, paramSessionId, false); // expire when browser close (client cookie)
- return xxlUser;
- }
- return null;
- }
三, 快速入门(基于 Token)
3.1 "认证中心(SSO Server)" 搭建
"认证中心" 搭建成功后, 默认为 Token 方式登陆提供 API 接口如下:
1, 登陆接口:/App/login
参数: POST 参数
username: 账号
password: 账号
响应: JSON 格式
code:200 表示成功, 其他失败;
msg: 错误提示
data: 登陆用户的 sso sessionid
2, 注销接口:/App/logout
参数: POST 参数
sessionId: 登陆用户的 sso sessionid
响应: JSON 格式
code:200 表示成功, 其他失败;
msg: 错误提示
3, 登陆状态校验接口:/App/logincheck
参数: POST 参数
sessionId: 登陆用户的 sso sessionid
响应: JSON 格式
code:200 表示成功, 其他失败;
msg: 错误提示
data: 登陆用户信息
userid: 用户 ID
username: 用户名
2.2 部署 "单点登陆 Client 端接入示例项目" (Token 方式)
项目名: xxl-sso-token-sample-springboot
2.3 验证 (模拟请求 Token 方式接入 SSO 的接口)
环境准备: 启动 Redis, 初始化 MySQL 表数据;
修改 Host 文件: 域名方式访问认证中心, 模拟跨域与线上真实环境
- ### 在 host 文件中添加以下内容 0
- 127.0.0.1 xxlssoserver.com
- 127.0.0.1 xxlssoclient1.com
- 127.0.0.1 xxlssoclient2.com
分别运行 "xxl-sso-server" 与 "xxl-sso-token-sample-springboot"
1,SSO 认证中心地址:
http://xxlssoserver.com:8080/xxl-sso-server
2,Client01 应用地址:
http://xxlssoclient1.com:8082/xxl-sso-token-sample-springboot/
3,Client02 应用地址:
http://xxlssoclient2.com:8082/xxl-sso-token-sample-springboot/
SSO 登录 / 注销流程验证
可参考测试用例 :com.xxl.App.sample.test.TokenClientTest
正常情况下, 登录流程如下:
1, 获取用户输入的账号密码后, 请求 SSO Server 的登录接口, 获取用户 sso sessionid ;(参考代码: TokenClientTest.loginTest)
2, 登陆成功后, 获取到 sso sessionid , 需要主动存储, 后续请求时需要设置在 Header 参数 中;
3, 此时, 使用 sso sessionid 访问受保护的 "Client01 应用" 和 "Client02 应用" 提供的接口, 接口均正常返回;(参考代码: TokenClientTest.clientApiRequestTest)
正常情况下, 注销流程如下:
1, 请求 SSO Server 的注销接口, 注销登陆凭证 sso sessionid ;(参考代码: TokenClientTest.logoutTest)
2, 注销成功后, sso sessionid 将会全局失效;
3, 此时, 使用 sso sessionid 访问受保护的 "Client01 应用" 和 "Client02 应用" 提供的接口, 接口请求将会被拦截, 提示未登录并返回状态码 501 ;(参考代码: TokenClientTest.clientApiRequestTest)
四, 总体设计
4.1 架构图
4.2 功能定位
XXL-SSO 是一个分布式单点登录框架. 只需要登录一次就可以访问所有相互信任的应用系统.
借助 XXL-SSO, 可以快速实现分布式系统单点登录.
4.3 核心概念
概念 | 说明 |
---|---|
SSO Server | 中央认证服务,支持集群; |
SSO Client | 接入 SSO 认证中心的 Client 应用; |
SSO SessionId | 登录用户会话 ID,SSO 登录成功为用户自动分配; |
SSO User | 登录用户信息,与 SSO SessionId 相对应; |
4.4 登录流程剖析
用户于 Client 端应用访问受限资源时, 将会自动 redirect 到 SSO Server 进入统一登录界面.
用户登录成功之后将会为用户分配 SSO SessionId 并 redirect 返回来源 Client 端应用, 同时附带分配的 SSO SessionId.
在 Client 端的 SSO Filter 里验证 SSO SessionId 无误, 将 SSO SessionId 写入到用户浏览器 Client 端域名下 cookie 中.
SSO Filter 验证 SSO SessionId 通过, 受限资源请求放行;
4.5 注销流程剖析
用户与 Client 端应用请求注销 Path 时, 将会 redirect 到 SSO Server 自动销毁全局 SSO SessionId, 实现全局销毁;
然后, 访问接入 SSO 保护的任意 Client 端应用时, SSO Filter 均会拦截请求并 redirect 到 SSO Server 的统一登录界面.
4.6 基于 Cookie, 相关概念
登陆凭证存储: 登陆成功后, 用户登陆凭证被自动存储在浏览器 Cookie 中;
Client 端校验登陆状态: 通过校验请求 Cookie 中的是否包含用户登录凭证判断;
系统角色模型:
SSO Server: 认证中心, 提供用户登陆, 注销以及登陆状态校验等功能.
Client 应用: 受 SSO 保护的 Client 端 Web 应用, 为用户浏览器访问提供服务;
用户: 发起请求的用户, 使用浏览器访问.
4.7 基于 Token, 相关概念
登陆凭证存储: 登陆成功后, 获取到登录凭证(xxl_sso_sessionid=xxx), 需要主动存储, 如存储在 localStorage,SQLite 中;
Client 端校验登陆状态: 通过校验请求 Header 参数 中的是否包含用户登录凭证 (xxl_sso_sessionid=xxx) 判断; 因此, 发送请求时需要在 Header 参数 中设置登陆凭证;
系统角色模型:
SSO Server: 认证中心, 提供用户登陆, 注销以及登陆状态校验等功能.
Client 应用: 受 SSO 保护的 Client 端 Web 应用, 为用户请求提供接口服务;
用户: 发起请求的用户, 如使用 Android,iOS, 桌面客户端等请求访问.
4.8 未登录状态请求处理
基于 Cookie, 未登录状态请求:
页面请求: redirect 到 SSO Server 登录界面;
JSON 请求: 返回未登录的 JSON 格式响应数据
数据格式:
code:501 错误码
msg:sso not login.
基于 Token, 未登录状态请求:
返回未登录的 JSON 格式响应数据
数据格式:
code:501 错误码
msg:sso not login.
4.9 登录态自动延期
支持自定义登录态有效期窗口, 默认 24H, 当登录态有效期窗口过半时, 自动顺延一个周期;
4.10 记住密码
未记住密码时, 关闭浏览器则登录态失效; 记住密码时, 登录态自动延期, 在自定义延期时间的基础上, 原则上可以无限延期;
4.11 路径排除
自定义路径排除 Path, 允许设置多个, 且支持 Ant 表达式. 用于排除 SSO 客户端不需要过滤的路径
来源: https://www.cnblogs.com/huoyuer/p/13295211.html