单点登录

<< 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回调接口。

SingeLogin

从以上原理图中可以发现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地址