1. 概述
1.1 版本
| 報表伺服器版本 | 插件版本 |
|---|---|
| 10.0&11.0 | 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、資料請求
該方式實際上是模擬一次請求的動作，需配置請求類型、請求地址、請求頭、請求體，可按照客戶提供的API文檔進行配置。
其中請求地址、請求頭、請求體的參數值支援公式寫法，也可以從前置步驟中獲取定義好的參數
請求結果寫法範例：
| 參數名 | API請求結果範例 | 參數值 | 配置說明 |
| userId | { "status": "1", | data.accountId | API傳回結果為簡單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 | API傳回結果為複雜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等，效果同參數獲取步驟，實現參數預定義，認證API地址和後續步驟中可引用對應參數
配置項 | 參數名 |
|---|---|
| Client ID | ${client_id} |
| Client Secret | ${client_secret} |
| Grant Type | ${grant_type} |
| Scope | ${scope} |
| State | ${state} |
| Token Name | 實際填入的值，範例：填入 code，在下面可使用 ${code} 來獲取該參數值 |
認證API地址：未登入帆軟決策平台時，跳轉到客戶Oauth2.0認證平台的地址，範例： ${"http://ip:port/oauth/login?redirect=" + URLEncode(requestURL)+ "&client_id=" + client_id + "&scope=" + scope}
2、令牌申請
基於登入認證平台後攜帶的【Token Name】：code，請求客戶API獲取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中攜帶參數需API認證進行單點登入
本範例應用了自訂配置中的【資料請求】方式，基於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 | |
| 認證API地址 | ${"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)} |
| JwtEncode/JwtDecode | JWT加密/解密 | ${JwtEncode(accessToken, "FineReport2018", 60000)}
${JwtDecode(accessToken, "FineReport2018")}
|
| URLEncode/URLDecode | URL編碼/解碼 | ${URLEncode(accessToken)} ${URLDecode(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中內建公式；公式寫法不區分大小寫
