操作教程|如何将DataEase开源工具嵌入第三方系统?

发布于 2022年09月15日

编者注:本文选自DataEase官方知识库。

原文链接:
https://kb.fit2cloud.com/archives/122

在企业日常的使用中,经常有将DataEase开源数据可视化分析平台嵌入到第三方系统的需求。这样一来,DataEase就可以作为第三方系统中的某个菜单项,在点击相关选项后即可直接打开DataEase页面,并进行相关操作。

DataEase开源工具嵌入第三方系统的效果示意图如下:

本文主要分享如何通过单点登录和模拟登录两种方式进行接口对接,从而实现将DataEase嵌入到第三方系统的实际效果。为了方便描述,本文将所示例的第三方系统统一称为“A系统”。

方案概述

DataEase支持使用iframe嵌套到第三方系统中,关键问题在于如何统一两个系统的用户认证,即用户在A系统中打开DataEase系统时,无需再次登录,DataEase可以自动登录至A系统中的账户。目前有两种解决方案:即单点登录和模拟登录。

1.1 单点登录

使用支持OIDC或CAS协议的系统作为统一登录平台,A系统与DataEase全部对接到同一个单点平台,实现只需一次登录就可访问两个系统,即单点登录(Single Sign On,SSO)。

单点登录方式是DataEase原生支持的用户登录集成方式,仅需修改前端iframe嵌套即可。使用单点登录的方式,用户可以使用同一个密码登录两个平台,DataEase中不存在的用户在登录时会自动创建。单点登录方式在配置和使用方面更加方便,是比较推荐的方式。

1.2 模拟登录

A系统后台请求DataEase的登录接口,将登录成功的Token写入Cookie中,以模拟用户登录的过程,省去用户自己输入密码登录的过程。

有些情况下受限于业务系统,部分用户的第三方系统没有对接SSO系统,这种情况下可以使用模拟登录的方式,通过做一些开发实现想要的效果。

单点登录方式的实现过程

2.1 流程描述

目前,DataEase开源数据可视化分析平台支持OIDC、CAS协议,如果DataEase与A系统均已对接同一个单点登录系统,那么通过单点登录方案集成嵌入DataEase的整体流程如下:

1. 用户通过单点登录系统登录至A系统;

2. 用户点击相应菜单项,访问DataEase系统;

3. DataEase通过单点登录系统获取到当前登录用户信息,自动登录并重定向至DataEase首页;

4. 用户在A系统Web页面通过iframe嵌套使用DataEase系统功能。

2.2 配置指南

1. 配置OIDC或CAS;

2. 默认登录方式修改为“OIDC”;

3. 单点登录配置好后,在A系统中使用iframe地址访问DataEase地址即可。

模拟登录方式的实现过程

3.1 流程描述

1. 用户登录A系统;

2. 用户在A系统中通过iframe访问A系统的模拟登录接口;

3. A系统根据已登录的用户信息请求DataEase的用户查询接口,获取到DataEase系统中对应的用户ID;

4. A系统根据用户ID调用DataEase的用户密码修改接口,修改用户密码;

5. A系统调用DataEase的模拟登录接口获取Token;

6. A系统将Token写入Cookie中,并重定向至DataEase页面(当浏览器Cookie中存在Token时,访问DataEase便不再需要认证);

7. 用户在A系统Web页面通过iframe嵌套使用DataEase系统功能。

3.2 开发指南

此方案需要A系统提供一个模拟登录接口,并且在登录前修改DataEase中的用户密码以保证模拟登录成功。由于模拟登录是使用Cookie来实现,所以需要保证A系统与DataEase处于同一个根域名下。

3.2.1 DataEase提供的接口

1. API认证方式

DataEase接口调用时需要在请求头中传递accessKey和signature。

其中accessKey为下图中的Access Key的值,Access Key和Secret Key获取方式如下图所示。

signature为Access Key和Secrent Key拼接后使用AES加密计算出的结果,计算方式如下:

图示代码可参考此链接:
https://github.com/liuboF2c/dataease-login-adpter-demo/blob/main/src/main/java/dataease/lboo/demo/controller/DataEaseLoginController.java。

2. 用户查询接口

由于修改用户密码接口需要使用用户ID,我们首先需要使用用户查询接口获取用户ID。

其中operator的取值可参考源码,比如“eq”代表SQL中的“=”。

field取值参考数据库中sys_user表的字段名,例如username、nick_name等。

3. 修改用户密码接口

通过用户密码修改接口,修改用户密码。此处请求参数中的userId为上一步返回值中获取到的userId。

4. 登录接口

使用登录接口可获取到Token,将Token放入浏览器Cookie中后访问DataEase便不再需要登录认证。

登录接口中的password和username均需使用RSA加密,加密密钥取自DataEase源码中application.properties文件。

加密方式如下:

图示代码可参考此链接:

https://github.com/liuboF2c/dataease-login-adpter-demo/blob/main/src/main/java/dataease/lboo/demo/controller/DataEaseLoginController.java。

3.2.2 嵌套对接示例代码

基于以上接口,我们就可以实现将DataEase嵌入第三方系统。我写了一个Demo示例(下称Demo系统)供大家参考:
https://github.com/liuboF2c/dataease-login-adpter-demo。

使用此示例需注意以下事项:

1. Demo系统必须与DataEase处于同一域名下;

你可以通过修改本地hosts文件来实现,比如我进行测试时在/etc/hosts中添加了如下映射:

127.0.0.1 localhost.fit2cloud.com
10.2.3.23 edu.fit2cloud.com

2. 启动前,需要修改Demo系统代码,填充DataEaseLoginController中的变量值;

3. 页面嵌套参考如下代码,iframe中的src配置为后端的模拟登录地址;

4. 在A系统登出时,需清除Cookie,否则DataEase中的用户不会退出登录;

总结

DataEase支持使用iframe将系统嵌套到第三方系统中,同时DataEase还支持OIDC、CAS协议的单点登录系统的对接。通过单点登录或者模拟登录的方式,解决了两个系统用户认证的问题,从而实现了在第三方系统已登录时无需再次认证即可直接打开DataEase进行操作的效果。