1. 概述
1.1 版本
FineBI版本 | 插件版本 | SAML 版本 | 說明 |
---|---|---|---|
6.0 | V1.0.1 | 2.0 | |
6.0 | V1.0.2 | 2.0 | 新增配置項:「開啟debug模式」 詳見3.2節說明 |
6.0 | V1.0.3 | 2.0 | 新增欄位填寫完整性校驗 預設開啟「跨越SAML認證的請求-平台登入頁」 |
6.0 | V1.0.8 | 2.0 | 新增支援登出FineReport時,帳號同步從認證伺服器中登出 |
6.0/6.1 | V1.1.1 | 2.0 | 新增支援登出認證伺服器時,帳號同步從FineReport中登出 |
1.2 功能簡介
使用者需要實現透過SAML認證登入數據決策系統,本文提供配置 SAML 單點登入插件方案。
使用者可下載 SAML 單點登入插件,無需代碼,簡單快速地實現透過 SAML 認證登入數據決策系統的效果。
注:遠端設計時不走 SAML認證,預設放行。
2. 插件介紹
2.1 插件下載
請點選連結獲取插件試用安裝包:點選下載
伺服器-設計器插件安裝方法請參見:插件管理
2.2 頁面介紹
安裝插件後無需重啟,超管進入平台,點選「管理系統>系統管理」,新增「SAML-SP配置」頁面。
需注意以下幾點:
使用者需要有「管理系統」權限,才可見配置頁面。
支援熱部署,安裝啟用插件無需重啟工程。
修改配置無需重啟工程。
3. 操作步驟
3.1 開啟 SAML 單點登入
點選「開啟SAML單點登入」按鈕,如下圖所示:
3.2 SAML 配置
填寫設定項後,需點選「儲存」按鈕,如下圖所示:
注:未填寫完配置會導緻儲存失敗,如下圖所示:
各設定項介紹如下表所示:
設定項 | 說明 | 是否必填 |
開啟SAML單點登入 | 點選即可開啟SAML單點登入功能。 開啟後會載入filter攔截器,使用者存取原決策平台URL後,走單點邏輯。 注:無需重啟。 | / |
開啟debug模式 | 點選即可開啟插件debug模式。 開啟後會將saml單點登入過程中收集到的斷言資訊列印在fanruan.log的error級別日誌中。 注:建議一般不開啟,僅用於插件除錯,開啟後將會在日誌中匯出斷言內容,可能包含帳號、郵箱等資訊。 | / |
IDP元資料 | 填寫由身分認證工具提供的IDP原資料。 一般為xml格式的頁面,這裏需要填寫頁面所在的地址。 | 是 |
IDP唯一標識 | 填寫由身分認證工具提供的IDP唯一標識。 建議獲取方式:從IDP元資料中尋找“entityID”這一關鍵詞,後面的連結就是IDP唯一標識。 | 是 |
IDP SSO地址 | 填寫過濾器需要跳轉到的IDP地址。 不同IDP過程的獲取方式不同,需按照實際情況操作。 | 是 |
IDP公鑰 | 填寫IDP傳送斷言時加密所用的公鑰。 建議獲取方法:從IDP元資料中尋找“ds:X509Certificate”這一關鍵詞,關鍵詞後面的字串為公鑰。 | 是 |
帳號映射 | 此項為輔助功能,非必要項。 可使用IDP使用者聯動的其他屬性欄位進行單點登入,預設或為空時使用IDP傳回的“nameid”欄位,可以配置成其他欄位比如:username、email等。 | 否 |
SP唯一標識 | 填寫服務提供商的標識,自行配置即可。 | 是 |
SP 預設跳轉地址 | 填寫FineBI工程的存取路徑,url到/decision為止。 例如:https://localhost:37799/webroot/decision | 是 |
SP證書 | 上傳加密所用憑證,支援crt、cer、 pem格式。 也可使用預設的證書:cert.zip 。 | 是 |
SP私鑰 | 上傳鍵檔案,支援key格式。 注:如「SP證書」處使用了文檔提供的預設證書,此處需使用對應的key檔案:rsa_private.zip。 | 是 |
生成元資料xml檔案 | 點選按鈕,即可下載服務提供商所用的MetaData.xml檔案。 將MetaData檔案匯入到身分認證服務即可自動生成一個新SAML實體。 如果SP相關的5個屬性(IDP公鑰、SP唯一標識、SP預設跳轉地址、SP證書、SP私鑰)存在空值則提示:“請將sp相關資訊填寫完整”。 | 是 |
開啟SAML單點登出 | 選擇是否開啟saml單點登出功能。 開啟後展示“saml單點登出地址”配置項。 | 否 |
SAML單點登出地址 | 填寫跳出IDP的API,實現跳出FineBI同時跳出IDP。 參數說明: http://localhost:8080/auth/realms/FineReport/protocol/openid-connect/logout為idp的登出API部分 ?redirect_uri= 後面填寫登出後跳轉的位置,建議配置為FineBI登入頁面。 | 否 |
跳過SAML認證的請求-h5請求 | 是否放行h5請求。 開啟後h5不需要進行SAML認證,不開啟則只能透過SAML登入。 | 否 |
跳過SAML認證的請求-平台登入頁 | 開啟後允許使用決策平台登入頁進行登入。 注1:該配置預設開啟。 注2:如果不開啟,則只能透過SAML登入, 且未開啟SAML單點登出情況下,無法手動登出決策平台;如果開啟跳過,則跳出時會跳轉到FineBI原本的登入頁。 注3:配置測試單點時建議開啟,配置完成後若無需使用原平台登入頁,請關閉該配置,否則原平台登入入口將保留,地址為原URL+/login,例如:http://localhost:8075/webroot/decision/login。 | 否 |
自訂請求放行 | 自訂需要放行的請求,以分號;隔開不同請求。 請求路徑可以使用通配符。 欄位值範例:/webroot/decision/t*;/webroot/decision/map/edit | 否 |
注:只配置 SAML 登入,未配置 SAML 登出時:
未開啟「平台登入頁」:點選右上角的「跳出」按鈕,瀏覽器重新整理下頁面,不會登出。
開啟「平台登入頁」:點選右上角的「跳出」按鈕,強制跳轉到平台預設登入頁,但是實際上沒有登出平台,直接存取http://ip:埠/工程名/decision,還是顯示之前使用者的登入狀態。
3.3 關閉 SAML 單點
超管進入平台,點選「管理系統>系統管理>SAML-SP 配置」,關閉「開啟SAML單點登入」按鈕,點選「儲存」,如下圖所示:
4. 範例-Azure AD
注:如果需要執行從Azure AD發起的單一登入(例如從Azure AD的 My apps 單點到BI伺服器),須首先配置FineBI工程為https存取。配置https存取可參考:配置HTTPS 。
4.1 填寫SAML基礎設定
1. 填寫識別碼(實體識別碼)
此項自訂即可,例如本文範例此處填了工作人員姓名jade。
2. 填寫回覆URL (判斷提示取用者服務 URL)
此項需要填寫FineBI工程的存取路徑(結尾到decision) / sso/saml/acs,例如:https://localhost:37799/webroot/decision/sso/saml/acs
3. 填寫登入 URL
此項是azure ad內的必填項,用於執行從Azure AD發起的單一登入。若需要執行從Azure AD發起到FineBI伺服器的的單一登入(例如從Azure AD的My apps單點到FineBI伺服器),則需要先配置FineBI工程為https存取,配置https存取可參考:配置HTTPS 。
若已配置平台為HTTPS存取,則此處直接填寫FineBI工程的存取路徑即可,例如:https://localhost:37799/webroot/decision 。
若無此場景需求,可以填寫任意https的連結。
4. 填寫完必填項後,點選「儲存」按鈕。
4.2 在FineBI中完善配置項
FineBI中配置項 | 對應AzureAD資訊 |
---|---|
IDP元資料 | 應用過程同盟中繼資料 URL |
IDP唯一標識 | Azure AD 識別碼 |
IDP SSO地址 | 登入 URL |
IDP公鑰 | 點選下載證件 (Base64),下載後用記事本獲取內容 |
SP唯一標識 | 同上述4.1節第一點,自訂的值 |
SP預設跳轉地址 填寫FineBI工程的存取路徑,url到/decision為止 | / |
上傳SP證書和SP私鑰 這邊僅僅用作SAML報文的加密,上傳任意一份可以用作加密功能的證書即可. | / |
預設開啟「跨越SAML認證的請求-平台登入頁」 如果不開啟,則只能透過SAML登入, 且未開啟SAML單點登出情況下,無法手動登出決策平台;如果開啟跨越,則跳出或直接存取原登入頁URL \login時會跳轉到FineBI原本的登入頁。 注:配置測試單點時建議開啟,配置完成後若無需使用原平台登入頁,請關閉該配置,否則原平台登入入口將保留,地址為原URL+/login,例如:http://localhost:8075/webroot/decision/login。 | / |
4.3 效果查看
存取原報表連結 https://localhost:37799/webroot/decision,會進行SAML單點登入。
點選跳出登入當前使用者,會傳回到https://localhost:37799/webroot/decision/login。如下圖所示:
5. 範例-ADFS
5.1 ADFS 設定
1. 開啟ADFS, 選擇「Start> Administrative Tools > ADFS Management」,跳轉至「Relying Party Trusts」資料夾。
2. 選擇「Action > Add Relying Party Trust」。
3. 選擇「Start」來運作「Add Relying Party Trust Wizard」。
4. 開啟「Select Data Source」視窗,選擇 「Import data about the relying party from a file」, 選擇從插件配置頁上傳的metadata.xml檔案並點選「Next」。
5. 選擇「Next」,跳過「Configure Multi-factor Authentication Now?」訊問視窗。
6. 開啟「Choose Issuance Authorization Rules」視窗, 選擇 「Permit all users to access this replying party」 並點選 「Next」。
7. 在 「Ready to Add Trust」 視窗:
點選「Encryption」, 從FineBI伺服器上傳「SP Certificate」(SP允許證); 點選「Advanced」, 設定為「SHA-1」。
8. 開啟「Ready to Add Trust」視窗, 點選「Next」。
9. 開啟「Finish」 視窗, 點選「Open the Edit Claim Rules dialog for this replying party trust when the wizard closes」 並點選「Close」。
如果在關閉向導時沒有彈出「Edit Claim Rules」對話框, 右鍵選擇使用者設定的the Relying Party Trust名稱,並選擇「Edit Claim Rules...」。
10. 開啟 「Edit Claim Rules」對話框, 選擇「Add Rule」。
11. 開啟「Select Rule Template」 對話框, 在「Choose Rule Type」下拉列選擇「Send LDAP Attributes as Claims」並點選「Next」。
12. 填寫「the Configure Rule」對話框:
在「Claim rule name」欄輸入「UseridentiferToNameID 」(可自訂)。
在 「Attribute store」欄選擇 「Active Directory」。
在 「LDAP Attribute」欄選擇「SAM-Account-Name」 (或帳號的任意屬性)。
在「Outgoing Claim Type」欄輸入「Name ID」。
注:帳號映射欄位應設定為相同的值。在一些ADFS版本中,允許使用自訂值而不限定於名稱ID,此處的設定應為與插件設定中的帳號映射相同。
13. 點選「Finish」。
5.2 常見問題及解決方案
注:V1.0.2版本新增除錯功能,無需除錯時請保持按鈕關閉。如遇問題可聯系技術支援協助使用除錯功能進行排查。
AD FS的正確XML響應將包含Name屬性,正確格式如下:
5.2.1 在檔案中找不到名稱ID
可能的原因:
1. 未配置「Outgoing Claim Mapping」。
2. 在一些ADFS版本中, 「Outgoing Claim Mapping」必須包含「Name ID」。
5.2.2 XML中未傳回名稱欄位
「Name」欄位(屬性名稱)未出現在ADFS傳回的XML中。
可能的原因:
1. SP SSL 證書未上傳至ADFS。
2. ADFS加密型別未設定為「SHA-1」。
5.2.3 找不到匹配的帳號
ADFS傳回的XML中存在「Name」欄位(屬性名稱),但登入應用過程無法識別。
可能的原因:
SAML插件中的「Username Mapping」與「Outgoing Claim Type」設定的值不同。
5.2.4 帳號不存在或密碼錯誤
ADFS傳回的XML中存在「Name」欄位(屬性名稱),但登入不成功。
可能的原因:
ADFS中設定為「Outgoing Claim Type」的欄位不是FineFeport中的「username」欄位。