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

于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.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参数中设置登陆凭证；
系统角色模型：