1. 概述
1.1 版本
| 报表服务器版本 | JAR 包版本 | 插件版本 |
|---|---|---|
| 10.0 | 2020/01/01 | v1.0.0 |
1.2 应用场景
支持在 Oauth2 认证标准下，进行单点配置，集成FineReport/FineBI平台
支持配置自定义的单点逻辑（参数加解密、数据请求等）
支持独立配置PC端和移动端（H5预览）单点逻辑（PC端和移动端可配置不同的单点登录策略）
1.3 注意事项
针对移动端配置单点逻辑，需提前安装HTML5插件，方可正常使用
v11版本插件安装支持热部署；v10版本插件安装、更新后需要重启报表工程；v11和v10配置修改都无需重启
v10版本下1.0.3及之前版本的插件更新会出现白屏问题，需要重启一次
2. 插件介绍
2.1 插件安装
点击下载插件：类Oauth2单点插件
设计器插件安装方法请参见：设计器插件管理
服务器安装插件方法请参见：服务器插件管理
2.2 页面介绍
插件安装成功后，登录数据决策系统，点击「管理系统>单点集成」，即可进入功能界面，如下图所示：
选择PC端访问或者移动端访问，开启单点配置（两者配置页面流程相同，后续以PC端访问为例，进行说明）
有Oauth2和自定义认证两种模式，可供选择，进行配置
3. 认证模式
无论哪种认证模式，其目的均为获取登录系统的用户名。所以在插件配置的最后一步，请求结果的配置中，参数名需要固定写成【fr_login_name】，参数值根据前置的配置确定
3.1 自定义认证模式
3.1.1 基本配置
点击自定义认证模式，开启单点功能，如下图所示：（Oauth2认证中，基本配置相同）
配置项功能说明如下表：
序号 | 配置名称 | 配置效果 | 补充说明 |
|---|---|---|---|
| 1 | 动态获取报表域名 | 实现平台报表域名动态/固定获取 | 动态（开启）：requesturl参数域名部分会动态获取 固定（关闭）：requesturl参数域名部分固定读取【报表服务器地址】
|
| 2 | 报表服务器地址 | 帆软平台的访问地址，示例： http://localhost:8075/webroot/decision | 用于后台无法正确获取到平台地址的转发场景 |
| 3 | 保留平台登录页 | 是否保留/decision/login登录页 | 开启：访问/decision/login地址，会展示帆软默认登录页 关闭：屏蔽/decision/login地址， |
| 4 | 平台登出地址 | 平台登出地址，可用于单点登出，示例： http://www.baidu.com | 平台登出后会跳转到该地址 |
| 5 | 登录失败处理逻辑 | 切换登录失败后处理逻辑 | 展示报错：单点步骤失败后，页面显示报错日志 展示默认登录页：单点步骤失败后，跳转到帆软默认登录页，用户可手动输入账号密码进行再次登录（注：若关闭了保留平台登录页，单点失败后不会展示默认登录页，可能会导致页面循环重定向） |
3.1.2 新建步骤
点击新建步骤，显示三种方式：参数获取，重定向和数据请求。三种方式可以自由排列组合，进行配置，最终目的是获取当前帆软平台中的用户名【fr_login_name】
1、参数获取
常见使用场景说明：
| 场景 | 参数名 | 参数值 | 说明 |
|---|---|---|---|
| 预定义参数值 | paramA | demo | 定义一个参数paramA，值为demo |
| 获取参数值 | paramB | ${paramA} | 定义一个参数paramB，值为参数 paramA 的值； 以下此类写法统称为公式写法，其写法与要求均一致 paramA 的来源一般包括两种：
|
| 计算参数值 | paramB | ${left(paramA, 3) + "_test"} | 定义一个参数paramB，值为公式计算的结果； 公式的写法逻辑与FR中相同，FR中的内置公式均可用，注意需将公式内容用 ${} 包裹起来； 补充的常用加解密公式示例见第五章 示例中的参数值为：取参数 paramA 的左边三位字符，并拼接 _test 字符串；例如 paramA 值为 demo，最终计算结果为 dem_test |
| 传递实际登录用户名 | fr_login_name | 上述任一写法 | 若将参数名定义为 fr_login_name ，则实际执行登录的用户名为参数值实际计算结果 |
如下图所示，通过配置两步参数获取，可以实现参数传递的效果，等同于固定以用户名demo进行登录。
2、重定向
常见使用场景：客户侧有统一认证平台，希望使用统一认证平台替代帆软默认登录页登录，统一认证平台登录后携带标识参数，如code、token等，跳转回帆软地址。
参数说明：
【重定向地址】：重定向的目标地址，此时通常会把原始访问链接地址（平台、报表链接等）当做URL参数拼接进去，作为登录后的回调。此时会引出一个固定参数 requesturl ，该参数可用于获取原始访问链接地址，支持公式写法
【Token参数名】：标识客户统一认证平台登录后，回调时携带的标识参数的参数名，例如code/token等。带有登录用户名的信息，后续基于该参数名进行解析，通过配置【fr_login_name】，获取登录用户名
配置示例：
| 重定向地址 | Token参数名 | 配置说明 |
|---|---|---|
| ${"http://ip:port/protal?redirect="+urlencode(requesturl)} | code | 当访问帆软平台、报表链接等所有需要进行登录认证链接时（不包括不需要登录认证即可访问的链接，例如模板认证放行的链接），如果URL链接中未携带code，则执行重定向动作； urlencode(requesturl) ，其中
例如访问地址为 ：http://localhost:8075/webroot/decision/view/report?viewlet=WorkBook6.cpt&aaa=123则重定向地址为：http://ip:port/protal?redirect=http%3A%2F%2Flocalhost%3A8075%2Fwebroot%2Fdecision%2Fview%2Freport%3Fviewlet%3DWorkBook6.cpt%26aaa%3D123 |
3、数据请求
该方式实际上是模拟一次请求的动作，需配置请求类型、请求地址、请求头、请求体，可按照客户提供的接口文档进行配置。
其中请求地址、请求头、请求体的参数值支持公式写法，也可以从前置步骤中获取定义好的参数
请求结果写法示例：
| 参数名 | 接口请求结果示例 | 参数值 | 配置说明 |
| userId | { "status": "1", | data.accountId | 接口返回结果为简单json数据格式时，可通过 . 拼接 key的格式， 获取到对应的字段值 该写法表示将 userId 参数，赋值为10087897 |
| userId | { "store": { "book": [{ "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 }], "bicycle": { "color": "red", "price": 19.95 } } } | $..book[2].author | 接口返回结果为复杂json数据格式时，可使用 jpath 语句来获取执行值
该写法表示将userId 参数，赋值为第二个book节点的author值 |
| fr_login_name | 上述任一写法 | 若将参数名定义为 fr_login_name ，则实际执行登录的用户名为参数值实际计算结果 |
3.2 Oauth2认证模式
当前最常用的授权码认证的方式，其实可以理解为一种约定俗成的自定义认证模式。配置逻辑固定，可按照客户提供的文档进行配置
3.2.1 基本配置
参考3.1.1节。如图所示
3.2.2 其他配置
1、初始参数
配置初始化参数，如client_id/sercret等，效果同参数获取步骤，实现参数预定义，认证接口地址和后续步骤中可引用对应参数
配置项 | 参数名 |
|---|---|
| Client ID | ${client_id} |
| Client Secret | ${client_secret} |
| Grant Type | ${grant_type} |
| Scope | ${scope} |
| State | ${state} |
| Token Name | 实际填入的值，示例：填入 code，在下面可使用 ${code} 来获取该参数值 |
认证接口地址：未登录帆软决策平台时，跳转到客户Oauth2.0认证平台的地址，示例： ${"http://ip:port/oauth/login?redirect=" + URLEncode(requestURL)+ "&client_id=" + client_id + "&scope=" + scope}
2、令牌申请
基于登录认证平台后携带的【Token Name】：code，请求客户接口获取accessToken
3、用户信息
基于accessToken，获取登录用户名进行登录
3.3 高级设置说明
v1.0.4及更高版本插件有高级设置选项
回调地址设置
某些认证中心需要校验回调地址，在登录认证中心后，系统只能将您重定向到固定的URL，这意味着如果需要单点登录到不同的报表链接，则无法实现。为了解决这个问题，可以使用自定义回调地址。除了固定的redirect_uri之外，可以新增一个自定义参数，例如state参数，来携带认证前访问的URL，回调到固定URL后，插件获取自定义参数的值为新的地址，重定向到新的地址中。
但是，有些认证中心对重定向时携带的参数也有限制。在这种情况下，可以打开“是否通过cookie传递”开关。在重定向之前，插件会将请求的URL存储到cookie中。在回调到帆软平台时，系统会再次重定向到cookie中存储的访问地址。
为方便配置，可优先选择通过cookie传递。
自定义报错页信息
设置后的效果是，当出现了插件报错，会展示设置的报错信息而不是真正的报错原因。这是一个不建议设置的项，因为它会影响判断错误原因。比如此处设置了“抱歉，出错了”，效果如下
展示日志页面
配置单点时遇到错误常常需要导出日志才能定位到原因，比较麻烦，打开“展示日志页面”开关后，便可以访问http://ip:port/webroot/decision/sso/plugin/log，查看单点插件输出的日志，此处日志等级和平台设置的日志等级相同。
4. 示例说明
4.1 根据URL中携带 &user=Anna 进行单点登录
本示例应用了自定义配置中的【参数获取】方式，但此种方式由于是采用用户名的明文进行登录，所以安全性较低。本示例只展示插件的简单功能，实际场景中应用较少。
4.1.1 配置
参数名配置为fr_login_name，参数值为Anna（帆软决策平台的用户）。如下图
此处也可以配置为任意参数名和参数值的拼接形式，均可以实现登录
4.1.2 效果
点击右上角的保存，登录网址：http://localhost:8075/webroot/decision?user=Anna。此时不需要输入账号、密码，直接进入Anna的决策平台界面
如果想要动态获取URL中传递的参数，可将参数值配置为${user}。这样就可以通过访问http://localhost:8075/webroot/decision?user=xxx，xxx为决策平台任一用户名，来实现动态用户名登录
4.2 根据URL中携带参数需接口认证进行单点登录
本示例应用了自定义配置中的【数据请求】方式，基于JWT加密生成密文，如下图所示：
意思是：将用户名Anna，通过密钥ceshi，采用JWT标准，加密后得到密文
4.2.1 配置
在实际的业务场景中，根据客户提供的配置文档进行配置即可。该示例的配置如下图：
具体参数配置见下表：
| 配置项 | 内容 |
|---|---|
| 请求地址 | POST/${"http://localhost:8075/webroot/decision/sso/test/jwt/decode/json?token=" + token} |
| 请求头 | 参数名：hk 参数值：hv |
| 请求体 | json 参数名：bk 参数值：bv 参数名：key 参数值：ceshi |
| 请求结果 | 参数名：fr_login_name 参数值：data |
在实际配置时，客户提供的配置文档中，会包含请求地址、请求头、请求体和请求结果的具体信息，包括加密方式等。
本示例中的JWT加密，只是为了演示方便，给出的一种加密方式，在实际情况下，需按照客户配置文档的要求进行配置
4.2.2 效果
使用postman进行模拟，完成配置参数后，发送请求，可以看到结果中，用户名Anna被解析了出来。访问的url为：http://localhost:8075/webroot/decision/sso/test/jwt/decode/json?token=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJBbm5hIiwiZXhwIjo
xNjY2NjA2Njc1fQ.D3K4xzmTZK070MA7nMMveh8sLH6fB3khJnEfd-CGoS0
token后的一串参数为前文中生成的密文
4.3 Oauth2单点登录认证
4.3.1 配置
在实际的业务场景中，根据客户提供的配置文档进行配置即可。在客户提供的配置文档中，有需要进行配置的各个参数、地址信息等。该示例的配置如下图：
初始参数：
令牌申请：
用户信息：
具体参数配置见下表：
| 大类 | 配置项 | 内容 |
|---|---|---|
| 初始参数 | Client ID | ci |
| Client Secret | cs | |
| Token Name | code | |
| Scope | sc | |
| State | st | |
| 认证接口地址 | ${"http://localhost:8075/webroot/decision/sso/test/oauth/login?redirect=" + URLEncode(requestURL)} | |
| 令牌申请 | POST/${"http://localhost:8075/webroot/decision/sso/test/oauth/access?code=" + code} | |
| 请求头 | 无 | |
| 请求体 | x-www-form-urlencoded | |
| 请求结果 | 参数名：access 参数值：data.access | |
| 用户信息 | 请求地址 | POST/http://localhost:8075/webroot/decision/sso/test/oauth/user |
| 请求头 | 无 | |
| form_data | ||
| 请求结果 | 参数名：fr_login_name 参数值：data.name |
4.3.2 效果
点击右上角的保存，登录网址：http://localhost:8075/webroot/decision，跳转到认证中心地址：http://localhost:8075/webroot/decision/
sso/test/oauth/login?redirect=http%3A%2F%2Flocalhost%3A8075%2Fwebroot%2Fdecision。
输入用户名后，登录到决策系统
5. 常用参数及公式写法
目前支持的公式以及一些固定参数的参数名如下表
| 公式名称 | 公式说明 | 示例 |
|---|---|---|
| requestURL | 获取访问链接地址的URL | ${"https://ip:port?redirect=" +requestURL} |
| Base64Decode/Base64Encode | base64编码/解码 | ${Base64Decode(accessToken)} |
| JwtDecode/JwtEncode | JWT加密/解密 | ${JwtEncode(accessToken, "FineReport2018", 60000)}
${JwtDecode(accessToken, "FineReport2018")}
|
| URLDecode/URLEncode | URL编码/解码 | ${URLDecode(accessToken)} ${URLEncode(accessToken)} |
| HexDecode/HexEncode | Hex编码/解码 | ${HexDecode(accessToken)} |
| AESDecrypt/AESEncrypt | AES加密/解密 | ${AESDecrypt("AES/ECB/NoPadding", HexDecode(yx_encrypt_ticket), "3.14159265358979")}
${AESEncrypt("AES/ECB/NoPadding", HexDecode(yx_encrypt_ticket), "3.14159265358979")}
|
| SM2Decrypt/SM2Encrypt | 国密sm2加解密 | ${SM2Decrypt(accessToken, "FineReport2018")} ${SM2Encrypt(accessToken, "FineReport2018")}
|
| SM4Decrypt/SM4Encrypt | 国密sm4加解密 | ${SM4Decrypt(accessToken, "FineReport2018")} ${SM4Encrypt(accessToken, "FineReport2018")}
|
| SM3Encrypt | 国密sm3加密 | ${SM3Encrypt(accessToken)} |
| MD5 | MD5签名 | ${MD5(accessToken)} |
注：支持FR中内置的公式；公式写法不区分大小写