<< Click to Display Table of Contents >> 单点登录复制链接 |
单点登录名为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
如果单点登录的开关是关闭的,你需要到bi.home的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地址。