单点登录名为Single Sign On，简称为SSO。SSO的定义是在多个应用系统中，用户只需要登录一次就可以访问所有相互信任的应用系统。
当用户将永洪集成到自己的系统时，可以在登录自己系统的同时登录永洪BI平台。用户可以使用单点登录的方式，在登录自己系统后，访问永洪，无需再次登录。
➢注意：
单点登录与WebAPI登录无关，WebAPI登录是调用接口前的认证，请不要混淆使用。
1.实现方式
在项目的集成中，一般是通过单点登录实现客户系统与永洪系统之间的免登陆跳转，单点登录常见的方式有很多种，比如oauth，oauth2，cas等。永洪产品内置一种单点的集成方案， 客户若没有统一的单点方案可以考虑使用。这种方案采用token验证的方式，下面详细介绍下这种方式。
2.token验证原理说明
客户在自己的系统中登录以后，希望能直接打开永洪的报告或者功能模块。这种方式需要在报告或者功能模块的url后面附带token参数，当点击报告或者模块的url时，永洪系统拦截这些请求，调用客户系统提供的回调接口（需要客户开发）验证token是否是合法生成的，验证通过后回调接口返回当前用户信息。永洪系统会判断当前用户是否已经存在，如果不存在，会创建该用户，创建好后就直接登录系统，不会出现登录页面。也有一种场景为多个客户系统均要跳转到永洪做单点登录，那么可以使用另外一个参数sysFlag，这个参数可以用来区分是哪个系统跳转过来的，该参数作用是为了区分多个系统token验证的回调接口，根据参数的不同选取不同的回调地址，如果没有该参数或者该参数为空字符串，就会去读取默认配置的url回调接口。
从以上原理图中可以发现token的生成及验证回调服务应在永洪之外，可由客户自行组织开发。最终客户只要保证跳转url中携带token，并提供回调验证地址即可。
token也是一种常见的较为安全的验证方式，不会暴露密码，验证逻辑也由客户来掌握。
➢客户开发Token和回调接口注意事项：
•Token生成建议采用随机方式，每次会话不应该相同，同一人的不同会话，不同人的不同会话也应不同；
•Token应只能用来做一次验证，被验证后必须丢弃， 防止被其他人利用。
•客户可以在生成token时，存储用户相关信息，然后url携带token跳转，等待永洪回调查询。
•客户应提供回调接口，永洪回传token验证时，根据token来返回当前用户相关信息。
3.token回调接口说明
3.1token回调接口说明
接口 |
说明 |
请求地址 |
地址没有限制，可以是任意地址。 ➢例如： http://ip:port/serviceName，可通过参数配置在产品里。 |
请求参数(post方式) |
➢示例token值： token: E2ABA91383139F9D4B4D7C1E0226FA1B |
请求类型（body） |
请求类型为x-www-form-urlencoded。 |
返回参数 |
{ "result": "success", "userId": "john", "userAlias": "john", "userEmail": "john@.com", "userRoles": "角色1,角色2", "userGroups": "组1/组1子组,组2/组2子组", "param":{ "department": "总部", "city": "北京", "xxx": "xxx" } } |
➢说明：
回调验证token接口，可以使用post方式验证，参数名是token，返回值对应永洪中用户的可存储属性。
回调验证token接口，验证成功返回的结果中必须有result和userId 。
result：success代表接口回调成功，其他值为失败，必填。
userId：永洪中的用户名，必填。
userAlias：用户别名，非必填。
userEmail：用户邮箱，非必填。
userRoles：用户角色，如果用户有多个角色以逗号分隔，非必填。
userGroups：用户组，如果用户属于多个组以逗号分隔，需写入组的全路径，多层级组以”/”分隔，非必填。
param：对应一个json对象，里面存储需要放到产品内置参数中的数据，可用来进行数据权限过滤，非必填。
3.2token传递方式
token可以放在url后面，也可以通过post提交放在header里面。放在url后面比较常见，
➢举例：
•访问首页
http://ip:port/bi/Viewer?token=E2ABA91383139F9D4B4D7C1E0226FA1B
•访问报告
http://ip:port/bi/Viewer?proc=1&action=viewer&db=典型功能演示/TopN&token=E2ABA91383139F9D4B4D7C1E0226FA1B
具体的访问方式可以参考Web页面集成章节，只需在url后添加一个参数token即可（区分参数别忘了加上&）。
3.3 客户的回调接口java代码举例
➢注意：
不能直接使用，需要客户完善。
package com.customer.service;
import java.io.IOException;
import javax.servlet.ServletException;
import javax.servlet.http.*;
public class TokenCheckServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
public TokenCheckServlet() {
super();
}
protected void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
String token = request.getParameter("token");
if(token == null || "".equals(token.trim())) {
// 客户自己的错误处理逻辑
return;
}
else {
// 校验token是否合法
StringBuilder responseStr = new StringBuilder();
if(check(token)) {
// token验证通过就返回当前登录用户。对应永洪系统中的用户名。
responseStr.append("{\"result\":\"success\",\"userId\":\"test\"}");
}
else {
// token验证没通过就不返回userId。
responseStr.append("{\"error\":\"james\"}");
}
response.getWriter().write(responseStr.toString());
}
}
private boolean check(String token) {
return true;
}
protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
doPost(request, response);
}
}
4. 标准单点登录部署样例
在完成集成后，进行单点登录配置，配置步骤如下：
1)配置单点登录的拦截器。
Yonghong/tomcat/webapps/bi/WEB-INF/web.xml配置Servlet，拦截产品请求，先采取单点登录的逻辑。
需要添加的内容：
<!-- sso filter start -->
<filter>
<filter-name>StandardSSOFilter</filter-name>
<filter-class>g5.sv.standardsso.SSOLoginFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>StandardSSOFilter</filter-name>
<servlet-name>ViewerServlet</servlet-name>
</filter-mapping>
<!-- sso filter end -->
2)配置bi.properties文件
Yonghong/bihome/bi.properties文件中修改以下属性：
➢举例：
standardsso.callback.url=http://ip:port/xx/TokenChecked（此处为举例，链接由客户系统提供，用于验证token信息 )
3)重启tomcat(This is an example, the link is provided by the client system to verify the token information )
如果单点登录的开关是关闭的，你需要到bihome的bi.properties中，配置standardsso.enabled=true，开启单点登录。
重启tomcat，单点登录的配置即会生效。
4)配置代理服务器。
常见的集成方式一般有两种，正常的url跳转，及iframe嵌入的方式。url跳转一般没有什么问题，但在iframe嵌入的情况下，不同浏览器由于自身安全的设计表现也不同，以chrome为例，自80版本时，chrome引入了samesite属性的机制，对于不同源的两个服务之间的调用是不被信任的。解决方案为通过nginx之类的代理服务， 将bi和需要集成的系统映射为同一个来源，避免跨域问题。
location /bi/ {
proxy_pass http://xx.xx.xx.xxx:8080/bi/;
proxy_set_header host $http_host;
proxy_set_header X-REAL-IP $remote_addr;
}
5. 单点登录时进行用户创建
当单点登录验证通过后，一般永洪会获取当前登录用户信息，可以检查当前访问用户是否在永洪系统中已经存在，如果用户不存在，需要参考下表配置参数，永洪系统中会创建对应的用户。这种方式比较灵活，但这种方式会遇到一个问题，就是在客户系统中删除的用户（可能离职等原因），将不会再访问永洪系统，但是永洪系统无法接收此信息，所以无法及时删除这些过期的用户，需要再考虑其他方式或者手动在永洪管理系统中删除。
（如需使用，可在bi.properties中进行配置）
配置项 |
类型 |
默认值 |
相关模块 |
描述 |
|---|---|---|---|---|
standardsso.enabled |
字符串 |
true |
标准单点登录 |
是否启用单点登录，默认是启用的。 |
standardsso. callback.url |
字符串 |
无 |
标准单点登录 |
客户系统提供的回调接口的url，用于验证token是否合法。 |
standardsso. callback.url. xxx |
字符串 |
无 |
标准单点登录 |
客户系统提供的多个回调接口的url，xxx的值为传入的sysFlag的值。 根据不同的sysFlag，选取相对应的回调url。 ➢例如： 传入的sysFlag为test，那么会去读取standardsso.callback.url.test属性对应的值为回调url，如果sysFlag为空，则会去默认读取standardsso.callback.url的地址。 |
standardsso. allowType |
字符串 |
无 |
标准单点登录 |
自动创建用户时需要给其设置访问永洪系统的权限，否则无法查看。可以给自动创建的用户配置1个或者多个权限，也可以不配置，多个值之间用英文逗号分隔，在配置上之后，当永洪检测到用户没有权限访问这些模块时，会自动赋予查看权限。默认为空，即不授予任何权限。 viewerDb : 授予访问报告权限（适用于嵌入永洪报告到客户系统中，只想给用户访问该报告的权限，系统会自动将url中的报告授予当前用户查看权限）。 viewerManager：授予查看报告功能模块权限（适用于嵌入永洪的功能模块到客户系统时，系统自动授予用户访问该功能模块的权限）。 editor：授予访问编辑报告模块权限（适用于嵌入永洪的功能模块到客户系统时，系统自动授予用户访问该功能模块的权限）。 query：授予访问新建查询模块权限（适用于嵌入永洪的功能模块到客户系统时，系统自动授予用户访问该功能模块的权限）。 conn : 授权访问新建数据源模块权限（适用于嵌入永洪的功能模块到客户系统时，系统自动授予用户访问该功能模块的权限） ml：授权访问深度分析模块（适用于嵌入永洪的功能模块到客户系统时，系统自动授予用户访问该功能模块的权限） ➢例如： standardsso.allowType=viewerDb,viewerManager,editor,query,conn,ml |
standardsso. autoCreateUser |
字符串 |
无 |
标准单点登录 |
是否自动创建用户，只有true或者false两个可选值。选择true时，Token接口返回来的用户在永洪中如果不存在，会自动创建到指定组中，新建用户的初始密码为8位随机数。选择false时，不会自动创建用户，会在页面提示用户不存在。 |
standardsso. saveUserDir |
字符串 |
无 |
标准单点登录 |
自动创建用户到某个用户组下。默认配置的组名是“单点登录”。（如果包含中文需要用unicode编码，纯英文不需要编码） ➢注意： •此用户组不需手动创建，系统会自动创建，建议都配置一个目录，这样方便以后查哪些用户是通过单点登录创建的。 •不能有 \\/:*?"<>| 特殊字符。 |
standardsso.autoUpdateGroup |
字符串 |
false |
标准单点登录 |
是否自动更新用户所属组，只有true或者false两个可选值，默认为false。选择true时，会根据接口返回来的用户组userGroups的参数值更新，当参数不为空或空字符串时，则更新用户到组下面（组不存在会自动创建）。选择false时，不会根据该参数去更新用户所属的组信息。 |
standardsso.autoUpdateRole |
字符串 |
false |
标准单点登录 |
是否自动更新用户的角色，只有true或者false两个可选值。选择true时，会根据接口返回来的用户角色userRoles的参数值更新，当参数不为空或空字符串，则更新用户的角色信息（角色不存在会自动创建）。选择false时，不会根据该参数去更新用户的角色信息。 |
standardsso.autoUpdateUser |
字符串 |
false |
标准单点登录 |
是否自动更新用户信息，只有true或者false两个可选值。选择true时，会根据接口返回来的用户信息更新用户信息。选择false时，不会更新用户信息。 |
standardsso.anonymous.url |
字符串 |
api,TokenChecked |
标准单点登录 |
不进行单点登录拦截的url，当用户请求这些url时将直接放行，而不进行单点登录验证。需要配置回调url。 ➢例如： api,TokenChecked |
standardsso.token.invalid.jumpurl |
字符串 |
无 |
标准单点登录 |
当token校验接口成功，但返回的状态不对时，如果配置该跳转地址，则跳转到此url。 |
6. 单点退出
单点退出需在前端调用ip:port/bi/Viewer?proc=11&action=logout&isJs=true，同时可以指定登出的跳转页面，配置参数logout.redirect.url，参数详情参考系统界面配置-URL地址。