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

Posted 2022-09-16 FIT2CLOUD飞致云

编者注：本文选自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进行操作的效果。