深度剖析分布式单点登录框架XXL-SSO

蓝咒 提交于 2021-02-16 20:47:38

                                                           

于2018年初,在github上创建XXL-SSO项目仓库并提交第一个commit,随之进行系统结构设计,UI选型,交互设计……

于2018-12-05,XXL-SSO参与"2018年度最受欢迎中国开源软件"评比,在当时已录入的一万多个国产开源项目中角逐,最终排名第55名。

于2019-01-23,XXL-SSO被评选上榜"2018年度新增开源软件排行榜之国产 TOP 50"评比,排名第8名。

至今,XXL-SSO已接入多家公司的线上产品线,接入场景如电商业务,O2O业务和核心中间件配置动态化等,截止2018-03-15为止,XXL-SSO已接入的公司包括不限于:

  1. 湖南创发科技

  2. 深圳龙华科技有限公司

  3. 摩根国际

  4. 印记云

一、简介

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 下载

文档地址

  • 中文文档

源码仓库地址

源码仓库地址 Release Download
https://github.com/xuxueli/xxl-sso Download
https://gitee.com/xuxueli0323/xxl-sso Download

技术交流

  • 社区交流

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

@Beanpublic 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 "," separatedxxl.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文件中添加以下内容0127.0.0.1 xxlssoserver.com127.0.0.1 xxlssoclient1.com127.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

    • code:200 表示成功、其他失败;
    • msg:错误提示
    • data: 登陆用户的 sso sessionid
    • username:账号
    • password:账号
    • 参数:POST参数
    • 响应:JSON格式
  • 2、注销接口:/app/logout

    • code:200 表示成功、其他失败;
    • msg:错误提示
    • sessionId:登陆用户的 sso sessionid
    • 参数:POST参数
    • 响应:JSON格式
  • 3、登陆状态校验接口:/app/logincheck

    • code:200 表示成功、其他失败;
    • msg:错误提示
    • data:登陆用户信息
    • userid:用户ID
    • username:用户名
    • sessionId:登陆用户的 sso sessionid
    • 参数:POST参数
    • 响应:JSON格式

2.2 部署 "单点登陆Client端接入示例项目" (Token方式)

项目名:xxl-sso-token-sample-springboot

2.3 验证 (模拟请求 Token 方式接入SSO的接口)

  • 环境准备:启动Redis、初始化Mysql表数据;

  • 修改Host文件:域名方式访问认证中心,模拟跨域与线上真实环境

### 在host文件中添加以下内容0127.0.0.1 xxlssoserver.com127.0.0.1 xxlssoclient1.com127.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客户端不需要过滤的路径


< END >


作者:bdcyouth


BDC+

专注于互联网年轻人的社区


微信扫描二维码,关注我们的公众号


本文分享自微信公众号 - Zechen的小本本(NotesOfZechen)。
如有侵权,请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”,欢迎正在阅读的你也加入,一起分享。

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!