1. 概述编辑
1.1 版本
报表服务器版本 | JAR 包版本 | 插件版本 |
---|---|---|
10.0 | 2020/01/01 | v1.0.0 |
1.2 应用场景
支持 Oauth2 认证框架单点集成帆软fr/bi平台
支持配置自定义的单点逻辑(参数加解密、数据请求等)
支持PC端和移动端(H5预览)独立配置单点逻辑
注:1. 远程设计请求未拦截
2. 移动端配置针对H5页面预览,需确认已安装HTML5插件
3. v11版本插件安装支持热部署;v10版本插件安装、更新后需要重启报表工程;v11和v10配置修改都无需重启
2. 插件介绍编辑
2.1 插件安装
点击下载插件:类Oauth2单点插件
设计器插件安装方法请参见:设计器插件管理
服务器安装插件方法请参见:服务器插件管理
2.2 配置页面
打开 【管理系统】-【单点集成】选项,展示页面如下:
选择PC或者移动端(H5预览)进行单点逻辑配置 (PC端和移动端可配置不同的单点登录策略)
2.3 示例说明
示例一:根据URL中携带 &user=tom 进行单点登录
单点的整体逻辑其实都是为了最终能获取到当前帆软平台中的用户名 ,然后我们通过用户名后台代码登录来实现浏览器登录的效果。
所以我们约定了一个用来指示用户名的固定参数名 【fr_login_name】
比如,我们在自定义配置(截图是一个 【参数获取】流程,流程具体说明参考 2.4-步骤:参数获取 )中按照如下配置保存,会发生什么?
答案就是,当访问所有需要登录页面时,都会以 tom 用户来登录,因为配置的 【fr_login_name】 参数值是固定 tom 。
====================================================================================================
下面我们拓展下,如果想要动态获取URL中传递的参数要怎么配置呢?
为了便于我们更好的理解,所以在所有可配置的地方都继承了我们FR中默认公式的写法,例如可通过 ${param} 来获取指定参数,更多公式示例可参考 2.5 ;
有了获取参数的方法,我们要考虑怎么从 URL 中拿到携带参数呢? 这个插件其实已经帮我们处理好了,会自动读取出报表链接中携带的 query 参数;
有了上面两个步骤的准备,其实我们从URL中动态获取参数就可以简单写成下面的格式,这样我们访问 /decision?user=xxx,就会以动态的用户名(user参数值)来登录了。
示例二:根据URL中携带用户名加密后的参数进行单点登录
如果我们的用户名是基于JWT加密生成的密文(指 payload 的 subject 字段记录用户名),我们应该如何配置呢?
这就需要我们在公式中支持 JWT 解密的动作才行,所以插件也内置了部分常用加解密公式供大家使用,更多公式示例可参考 2.5;
找到 JWT解密公式 JwtDecode 再传入响应的参数即可 ,所以我们在参数值处填入 ${JwtDecode(token, "FineReport2018")} ,FineReport2018 为示例秘钥值,
如此我们访问 /decision?token=xxx,就会以动态的用户名(subject 记录的用户名)来登录了 。
2.4 步骤说明
下面介绍下我们【自定义认证模式】中的三种步骤分别有什么作用,
步骤:参数获取
示例一中有作演示,这个步骤主要是用于定义一些参数获取的获取动作,包括从 URL query 中获取,或者我们预定义的一些常量参数等。
这个地方有个比较重要逻辑要说明下,在前置步骤中定义的参数名,在后置步骤中是可以获取到对应参数值的,
可以看下面截图,其实就是个参数传递的效果,它的效果也是也还是都固定以 tom 来登录。
步骤:数据请求
看下面截图示例,大家也大概能看出来,这其实就是个模拟一次请求的动作,请求类型、请求地址、请求头、请求体 参考客户提供的接口文档对照配置就可以了;
其中请求地址、请求头、请求体 的参数值都是支持公式写法的,当然也可以从前置步骤中获取定义好的参数。
请求结果要如何配置呢?下面给个示例,我们要从这个结果里面获取 accountId,要怎么写?
参考上面的截图,以 key 和 . 来拼接,最终定位到我们需要获取的字段就可以了。
当然如果返回结果不是用户名,而只是一个中间值,参数名可以不定义为 【fr_login_name】,供后续步骤继续引用。
对于一些复杂结构的返回结果怎么解析呢,插件也提供了 JSONPATH 的写法,可以参考下如下示例。
针对上述json示例写法说明如下
步骤:重定向
我们最经常遇到的一个单点场景是什么样的呢,客户有一个自己的认证平台,帆软平台登录时要跳转到统一的认证平台进行登录,
登录完成后再跳转回来并携带一个 code,我们需要基于 code 解析出用户名来登录,这其实就是类Oauth2 认证模式,
针对以上跳转场景我们要怎么实现呢,所以就有了这个重定向步骤。
【重定向地址】:需要跳转到的地址,这时候一般把原来访问的报表连接当做一个参数拼接到URL后面,这时候就会引出一个固定参数 【requestURL 】,它可以获取到跳转前访问的链接地址
【Token Name】:标识客户的认证平台登录后,回调时携带的标识参数的参数名,例如 token/code 之类
配置完这两个参数后的效果是什么样的呢?就是当报表链接中未识别到 Token Name 参数时,都会跳转到重定向的地址去。
注:上面提到的报表链接,并不是所有的报表链接和平台访问地址,而是需要登录认证的链接,例如访问平台页或者开启了模板认证的模板链接
至此,三种基本步骤的配置流程基本结束了。
2.5 常用参数及公式写法
下面我们整理下目前支持的公式以及一些固定参数的参数名
公式名称 | 公式说明 | 示例 |
---|---|---|
requestURL | 获取访问链接地址的完整URL地址 | ${"https://ip:port?redirect=" +URLEncode(requestURL)} |
Base64Decode/Base64Encode | Base64编码/解码 | ${Base64Decode(accessToken)} |
JwtDecode/JwtEncode | JWT加密/解密 加密:将明文放入 subject 字段,并添加超时时间 解密:校验token是否超时,未超时返回 subject 字段值 | ${JwtEncode(plain, "FineReport2018", 60000)}
${JwtDecode(token, "FineReport2018")}
|
URLDecode/URLEncode | URL编码/解码 | ${URLDecode(accessToken)} ${URLEncode(accessToken)} |
HexDecode/HexEncode | Hex编码/解码 | ${HexDecode(accessToken)} ${HexEncode(accessToken)} |
AESDecrypt/AESEncrypt | AES加密/解密
加密:返回BASE64编码后字符串 解密:密文需先进行BASE64编码 | ${AESDecrypt(plain, "3.14159265358979")}
${AESEncrypt(token, "3.14159265358979")}
|
SM2Decrypt/SM2Encrypt | 国密sm2加解密 | ${SM2Decrypt(token, privateKey)}
${SM2Encrypt(plain, publicKey)}
|
SM4Decrypt/SM4Encrypt | 国密sm4加解密
加密:返回BASE64编码后字符串 解密:密文需先进行BASE64编码 | ${SM4Decrypt(token, "3.14159265358979")} ${SM4Encrypt(plain, "3.14159265358979")}
|
SM3Encrypt | 国密sm3算法 | ${SM3Encrypt(plain)} |
MD5 | md5 签名 | ${MD5(plain)} |
注:
1. FR中内置的公式也是支持的
2. 公式写法不需要区分大小写
3. 认证模式介绍编辑
现认证模式包含有:【自定义认证模式】 和 【Oauth2认证模式】,下面大概说明下
基础配置
所有认证模板中均会包含【基本配置】项,该配置项功能说明如下:
序号 | 配置名称 | 配置效果 | 补充说明 |
---|---|---|---|
1 | 报表服务器地址 | 帆软平台的访问地址,示例:http://localhost:8075/webroot/decision | 用于一些转发场景后台无法正确获取到平台地址 |
2 | 保留平台登录页 | 是否保留 /decision/login 登录页 | 开启:访问/login地址会打开帆软默认登录地址 关闭:屏蔽/login地址,未登录时按照配置认证逻辑处理,已登录时会跳转到 /decision 页面 |
3 | 平台登出地址 | 平台登出地址,可用于单点登出 | 平台登出后会跳转到该地址 |
自定义认证模式
就是可以基于三种常用步骤进行自由排列组合的认证模式,保证最终一个步骤能正确获取到 【fr_login_name】就可以了。
Oauth2认证模式
目前实现授权码认证(最常用,其他场景等遇到可以补充进去),其实就是一种约定俗称的自定义认证模式,大体配置基本一致,基于客户提供的文档预定配置即可,大体流程如下:
初始参数:配置一些初始化参数,例如 client_id/sercret 等,认证接口地址 是指帆软未登录时跳转到客户Oauth2.0 认证平台的地址路径,
示例: ${"http://ip:port/oauth/login?redirect=" + URLEncode(requestURL)+ "&client_id=" + client_id + "&scope=" + scope}令牌申请:基于登录完成后携带的code请求客户接口换取到 accessToken
用户信息:基于accessToken换取到登录用户名进行登录
初始参数名映射表:
配置项 | 参数名 |
---|---|
Client ID | ${client_id} |
Client Secret | ${client_secret} |
Grant Type | ${grant_type} |
Scope | ${scope} |
State | ${state} |
Token Name | 实际填入的值,示例:填入 code,在下面可使用 ${code} 来获取该参数值 |