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 端）資訊：

SP 欄位	格式
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 伺服器上操作：

1. 開啟 Server Manager > Tools > AD FS Management

2. 左側選擇 Relying Party Trusts，右側點擊 Add Relying Party Trust...

3. 選擇 Claims aware > Start

4. 在 Select Data Source 頁面選擇匯入方式（見下方說明）

5. Display name 填入 MaiAgent

6. Access Control Policy 先選擇 Permit everyone（測試通過後再改為指定的 AD 群組）

7. 一路 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）

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
 => issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress", "http://schemas.microsoft.com/identity/claims/displayname"), query = ";mail,mail,displayName;{0}", param = c.Value);

這條規則從 AD 讀取使用者的 mail 與 displayName 屬性。特別注意：MaiAgent 讀取電子郵件用的是 Name 宣告（.../claims/name），不是一般慣用的 emailaddress 宣告，因此這條規則會把 Email 同時發送到兩個宣告中（屬性對應詳見 SAML 整合的屬性對應說明）。

規則二：Email 轉換為 NameID（名稱：Email to NameID）

c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"]
 => issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");

這條規則把 Email 轉為 Email 格式的 NameID，作為登入識別與單一登出之用。

設定時的三個注意事項：

• 規則順序：規則一在上、規則二在下（規則二依賴規則一發出的 emailaddress 宣告）

• 規則文字請整段複製貼上，不要手動輸入——宣告 URI 差一個字元整條規則就無效

• 儲存後不需重新啟動任何服務，直接測試登入即可

五、檢查信賴憑證者屬性

在 Relying Party 上按右鍵 > Properties：

分頁	檢查項目
Advanced	Secure hash algorithm 選擇 SHA-256
Encryption	不要放置任何加密憑證。MaiAgent 不支援加密的 SAML 判斷提示，放了憑證 ADFS 會加密回應，登入將失敗
Signature	保持空白即可

六、測試登入

1. 使用 AD mail 屬性有值的測試帳號

2. 從 MaiAgent 登入頁點選 SSO 登入，瀏覽器應跳轉到 https://{ADFS 網域}/adfs/ls/

3. 輸入 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 端不需變更