SAML 整合

透過 SAML 2.0 協定整合 Azure AD、Okta、Google Workspace 等身分提供者

SAML（Security Assertion Markup Language）是企業級應用廣泛採用的標準驗證協定。

適用對象：已建置 SAML 身分提供者的企業（如 Microsoft Entra ID / Azure AD、Okta、Google Workspace）

主要優勢：

• 業界標準協定，相容性高

• 支援完整的使用者屬性傳遞

• 可整合多因素驗證（MFA）

• 支援單一登出（Single Logout, SLO）

設定步驟

1. 在 MaiAgent 後台填寫 IdP 資訊

SAML 認證設定：填寫 IdP 資訊後系統會自動產生 SP 資訊

選擇 SAML 認證類型後，需要填寫以下欄位：

欄位	必填	說明
認證來源名稱	是	用於產生 SP 端點 URL，例如 my-company
IdP Metadata URL	是	身分提供者的中繼資料 URL
IdP Entity ID	是	身分提供者的實體識別碼
IdP SSO URL	是	身分提供者的單一登入端點 URL
Email Domain	否	可選填企業 Email 網域

2. 取得 SP（MaiAgent 端）資訊

填寫認證來源名稱後，系統會自動產生以下 SP 資訊，顯示在設定頁面中：

SP 欄位	格式	說明
Entity ID（實體識別碼）	https://{域名}/accounts/saml/{名稱}/metadata/	提供給 IdP 設定用
ACS URL（判斷提示取用者服務 URL）	https://{域名}/accounts/saml/{名稱}/acs/	提供給 IdP 設定用
Login URL（登入 URL）	https://{API 域名}/auth/saml/{名稱}/login/	SAML 登入入口

SP 資訊區域提供 複製 按鈕，方便您直接複製 URL 到 IdP 的設定介面。

3. 在身分提供者（IdP）設定 MaiAgent 應用程式

以 Microsoft Entra ID（Azure AD） 為例：

1. 登入 Azure Portal > Microsoft Entra ID > 企業應用程式

2. 點擊 新增應用程式 > 建立您自己的應用程式

3. 選擇「整合您在資源庫中找不到的其他任何應用程式（非資源庫）」

在 Azure AD 中建立自訂企業應用程式

1. 選取剛建立的企業應用程式

選取指定的企業應用程式

1. 進入企業應用程式，點選左側 單一登入 > SAML

選擇 SAML 作為單一登入方式

1. 在 基本 SAML 設定 區段填入 MaiAgent 的 SP 資訊：

   • 識別碼（實體識別碼）：填入 MaiAgent 產生的 Entity ID

   • 回覆 URL（判斷提示取用者服務 URL）：填入 MaiAgent 產生的 ACS URL

在基本 SAML 設定中填入 MaiAgent 的 Entity ID 和 ACS URL

1. 儲存設定

4. 從 IdP 取得設定值並填回 MaiAgent

在 Azure AD 的 設定 SAML 單一登入 頁面底部，找到以下資訊：

Azure AD 欄位	對應 MaiAgent 欄位
應用程式同盟中繼資料 URL	IdP Metadata URL
Microsoft Entra 識別碼	IdP Entity ID
登入 URL	IdP SSO URL

將這些值填入 MaiAgent 後台的 SAML 設定表單。

從 Azure AD 取得 Microsoft Entra 識別碼、登入 URL 和中繼資料 URL

5. 指派使用者與群組

在 Azure AD 的企業應用程式中，點選 使用者和群組 > 新增使用者/群組，將需要存取 MaiAgent 的員工或群組加入。

將需要存取 MaiAgent 的員工或群組加入企業應用程式

6. 儲存並確認

在 MaiAgent 後台點擊 儲存 按鈕，系統會跳出確認視窗，提醒您：

• 切換認證類型後，員工登入方式將改變

• 現有使用者需使用新的 SSO 方式登入

• 請確保 IdP 端設定已完成

確認後即完成設定。

SAML 屬性對應

MaiAgent 會從 SAML 回應（SAML Response）中擷取以下屬性：

SAML 屬性（Claim）	MaiAgent 欄位	說明
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	使用者電子郵件	必要欄位，作為使用者識別
http://schemas.microsoft.com/identity/claims/displayname	顯示名稱	顯示在介面中的使用者名稱

如果 SAML 回應中未包含 displayname 屬性，系統會自動擷取 Email 的前綴（@ 前方的文字）作為顯示名稱。

其他 SAML IdP 設定

MaiAgent 的 SAML 整合不限於 Microsoft Entra ID。只要您的身分提供者支援 SAML 2.0 標準協定，都可以完成整合。常見的 IdP 包括：

• Okta：在 Applications 中新增 SAML 2.0 App

• Google Workspace：在 Admin Console > Security > SSO 中設定

• ADFS：在 Relying Party Trusts 中新增

設定邏輯相同：將 MaiAgent 的 SP 資訊（Entity ID、ACS URL）填入 IdP，再將 IdP 的資訊（Metadata URL、Entity ID、SSO URL）填回 MaiAgent。

SAML 安全特性

• 支援 SAML 2.0 HTTP Redirect Binding

• Session Index 追蹤，確保登出操作的正確性

• NameID 格式使用 emailAddress，確保使用者識別一致性

• 登入 Cookie 設定：Secure=True、SameSite=None、HttpOnly=True，有效期 5 分鐘

設定欄位速查表

欄位	必填	格式	範例
認證來源名稱	是	小寫英數 + 連字號，max 31 字元	my-company
IdP Metadata URL	是	HTTPS URL	https://login.microsoftonline.com/.../federationmetadata/2007-06/federationmetadata.xml
IdP Entity ID	是	URI	https://sts.windows.net/{tenant-id}/
IdP SSO URL	是	HTTPS URL	https://login.microsoftonline.com/{tenant-id}/saml2
Email Domain	否	網域格式	company.com