部署与集成——单点登录

单点登录名为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)配置单点登录的拦截器。

vividime/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文件

vividime/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地址。