ADFS 整合
透過 SAML 2.0 協定整合企業內部的 ADFS(Active Directory Federation Services)
ADFS(Active Directory Federation Services)是微軟提供的企業身分聯合服務。已建置 Windows Active Directory 與 ADFS 的企業,可以讓員工直接使用 AD 帳號密碼登入 MaiAgent,不需另外建立帳號。
適用對象:已建置 ADFS(Windows Server 2016 / 2019 / 2022)的企業
開始前請準備:
MaiAgent 組織管理員權限(用於設定認證來源)
ADFS 伺服器的管理員權限(用於建立信賴憑證者信任與宣告規則)
一個 AD 帳號作為測試用,且該帳號的
mail屬性必須有值
整合的基本概念是「雙向交換資訊」:把 ADFS 的資訊(Metadata URL)填入 MaiAgent,再把 MaiAgent 的資訊(SP Metadata URL)匯入 ADFS。SAML 的通用設定說明請先參閱 SAML 整合。
一、在 MaiAgent 後台建立認證來源
進入 組織管理 > 認證來源,選擇 SAML 認證類型:
認證來源名稱
例如 my-company(小寫英數與連字號,用於產生 SP 端點 URL)
IdP Metadata URL
https://{ADFS 網域}/FederationMetadata/2007-06/FederationMetadata.xml
Email Domain
(選填)企業 Email 網域,例如 company.com
ADFS 的 Federation Metadata URL 是固定路徑,只要把 {ADFS 網域} 換成企業的 ADFS 主機網域即可。儲存時 MaiAgent 會即時抓取並解析這份中繼資料,自動帶入 Entity ID、SSO URL 與簽章憑證。
儲存時 MaiAgent 伺服器必須能連線到這個 Metadata URL。如果 ADFS 只開放內部網路存取、MaiAgent 無法連線,請改用手動模式:分別填入 IdP Entity ID(通常是 http://{ADFS 網域}/adfs/services/trust)、IdP SSO URL(通常是 https://{ADFS 網域}/adfs/ls/),以及從 ADFS 管理主控台匯出的 Token-Signing 憑證(Base64 格式)。
二、取得 MaiAgent 的 SP 資訊
儲存後,設定頁面會顯示 SP(Service Provider,即 MaiAgent 端)資訊:
Entity ID / SP Metadata URL
https://{平台網域}/accounts/saml/{名稱}/metadata/
ACS URL
https://{平台網域}/accounts/saml/{名稱}/acs/
用瀏覽器開啟 SP Metadata URL,確認會顯示一份 XML(以 <EntityDescriptor> 開頭),代表認證來源已生效。這個 URL 就是下一步要交給 ADFS 管理員的資料。
私有化部署若使用非標準連接埠(例如 https://平台網域:8000),請檢查 XML 中 AssertionConsumerService 的 Location 是否包含連接埠。如果 entityID 有連接埠、ACS URL 卻沒有,代表反向代理(Nginx)把 Host 標頭的連接埠去掉了——請將 Nginx 設定中的 proxy_set_header Host $host; 改為 proxy_set_header Host $http_host; 後重新載入 Nginx(注意每一個 location 區塊都要改),再重新整理確認。
三、在 ADFS 建立信賴憑證者信任
以下由 ADFS 管理員在 ADFS 伺服器上操作:
開啟 Server Manager > Tools > AD FS Management
左側選擇 Relying Party Trusts,右側點擊 Add Relying Party Trust...
選擇 Claims aware > Start
在 Select Data Source 頁面選擇匯入方式(見下方說明)
Display name 填入
MaiAgentAccess Control Policy 先選擇 Permit everyone(測試通過後再改為指定的 AD 群組)
一路 Next 完成精靈
Select Data Source 的兩種匯入方式:
Import data about the relying party published online
ADFS 伺服器信任 MaiAgent 的 TLS 憑證
貼入 SP Metadata URL
Import data from a file
MaiAgent 使用自簽憑證或內部憑證(常見於私有化部署)
先用瀏覽器開啟 SP Metadata URL、將 XML 另存成檔案,再選擇該檔案匯入
如果線上匯入出現「Could not create SSL/TLS secure channel」錯誤,代表 ADFS 伺服器不信任 MaiAgent 的憑證,改用檔案匯入即可。中繼資料匯入是一次性的動作,正式登入流程中 ADFS 不需要連線到 MaiAgent(所有跳轉都由使用者的瀏覽器完成),因此用檔案匯入沒有任何後遺症。
匯入成功後,精靈會自動帶入 Identifier(即 SP Metadata URL)與 ACS Endpoint,不需手動輸入。
四、設定宣告規則(Claim Rules)
這是整合中最容易遺漏的步驟。精靈跑完後宣告規則是空的,若不設定,ADFS 回傳的 SAML 回應不會帶任何使用者屬性,登入會直接失敗。
在剛建立的 Relying Party 上按右鍵 > Edit Claim Issuance Policy...(注意不是 Edit Access Control Policy)> Add Rule,範本選擇 Send Claims Using a Custom Rule,依序建立以下兩條規則。
規則一:發送使用者屬性(名稱:MaiAgent attributes)
這條規則從 AD 讀取使用者的 mail 與 displayName 屬性。特別注意:MaiAgent 讀取電子郵件用的是 Name 宣告(.../claims/name),不是一般慣用的 emailaddress 宣告,因此這條規則會把 Email 同時發送到兩個宣告中(屬性對應詳見 SAML 整合的屬性對應說明)。
規則二:Email 轉換為 NameID(名稱:Email to NameID)
這條規則把 Email 轉為 Email 格式的 NameID,作為登入識別與單一登出之用。
設定時的三個注意事項:
規則順序:規則一在上、規則二在下(規則二依賴規則一發出的 emailaddress 宣告)
規則文字請整段複製貼上,不要手動輸入——宣告 URI 差一個字元整條規則就無效
儲存後不需重新啟動任何服務,直接測試登入即可
五、檢查信賴憑證者屬性
在 Relying Party 上按右鍵 > Properties:
Advanced
Secure hash algorithm 選擇 SHA-256
Encryption
不要放置任何加密憑證。MaiAgent 不支援加密的 SAML 判斷提示,放了憑證 ADFS 會加密回應,登入將失敗
Signature
保持空白即可
六、測試登入
使用 AD
mail屬性有值的測試帳號從 MaiAgent 登入頁點選 SSO 登入,瀏覽器應跳轉到
https://{ADFS 網域}/adfs/ls/輸入 AD 帳號密碼,驗證成功後自動跳轉回 MaiAgent
首次透過 SSO 登入的使用者會自動建立帳號並加入組織,但預設沒有任何權限,會看到「No Access Permission」頁面——這是正常的安全設計。請組織管理員到 組織管理 > 成員 找到該成員並指派角色權限,使用者按下 Check Permission 或重新登入後即可使用。
疑難排解
ADFS 匯入中繼資料時顯示「Could not create SSL/TLS secure channel」
ADFS 伺服器不信任 MaiAgent 的 TLS 憑證(自簽或內部憑證)
改用「Import data from a file」檔案匯入
登入後停在「Third-Party Login Failure」
最常見是宣告規則問題,需查看伺服器記錄確認
私有化部署可執行 docker logs maiagent-django --since 5m 2>&1 | grep -i saml 查看錯誤訊息
記錄顯示 There is no AttributeStatement on the Response
宣告規則未設定,或測試帳號的 AD mail 屬性為空
依第四節補上兩條規則;用 Get-ADUser <帳號> -Properties mail 確認 mail 有值
記錄顯示 User email not found
宣告有發出,但 Email 沒有放在 Name 宣告
檢查規則一的宣告 URI 是否與文件完全一致
記錄顯示判斷提示過期或尚未生效(NotBefore / NotOnOrAfter)
MaiAgent 伺服器與 ADFS 伺服器時間不同步
兩邊主機都設定 NTP 校時
登入成功但顯示「No Access Permission」
新成員尚未被指派權限(正常行為)
管理員到成員管理指派角色權限
ADFS 驗證成功後跳轉的網址缺少連接埠、頁面無法開啟
SP 中繼資料中的 ACS URL 缺少連接埠(反向代理設定問題)
依第二節的提示修正 Nginx 的 proxy_set_header Host 設定,重新產生中繼資料並重新匯入 ADFS
善用 SAML-tracer 除錯:在瀏覽器安裝 SAML-tracer 擴充功能後重新登入一次,可以直接看到 ADFS 回傳的 SAML 回應內容。如果 AttributeStatement 是空的或 Email 放在錯誤的宣告中,一眼就能確認是 ADFS 端的宣告規則問題。
維運注意事項
Token-Signing 憑證輪替:ADFS 預設每年自動更換 Token-Signing 憑證(AutoCertificateRollover)。若 MaiAgent 端使用 IdP Metadata URL 模式設定,憑證更換後重新儲存一次認證來源即可更新;若使用手動憑證模式,必須在輪替前取得新憑證並更新設定,否則屆時所有使用者將無法登入
限縮登入對象:測試完成後,將 ADFS 的 Access Control Policy 從 Permit everyone 改為指定的 AD 群組,即可控制哪些員工能登入 MaiAgent,不需變更 MaiAgent 端設定
暫停 SSO:在 MaiAgent 後台關閉該認證來源的登入開關即可,ADFS 端不需變更
最後更新於
這有幫助嗎?
