Cloudflare Access 整合

使用 Cloudflare Zero Trust 的組織，可讓成員經 Cloudflare Access 驗證後登入 MaiAgent；說明設定欄位（Team Name、AUD Tag、電子郵件網域、自動建立成員）、登入流程與錯誤訊息。

如果貴公司已經用 Cloudflare Zero Trust 的 Access 管理內部系統的存取，可以把 Cloudflare Access 設成 MaiAgent 的第三方登入方式：成員點登入連結後，先在 Cloudflare Access（以及貴公司在 Access 後面串接的身分提供者）完成驗證，再自動登入 MaiAgent。

適用對象：已使用 Cloudflare Zero Trust Access、希望沿用同一套登入與存取政策的企業。

使用條件

• 組織為企業版方案。非企業版的組織在 管理操作 看不到 第三方登入設定。

• 只有組織擁有者可以儲存認證設定。

• 每個組織同一時間只能使用一種認證類型，切換時的影響見切換認證類型。

運作方式

1. 成員開啟 MaiAgent 產生的登入連結。

2. MaiAgent 把成員導向您設定的 伺服器 URL，也就是受 Cloudflare Access 保護的入口網址。

3. Cloudflare Access 攔下請求，要求成員依貴公司的 Access 政策登入。

4. 驗證通過後，Cloudflare 把附帶身分憑證的請求送到 MaiAgent。MaiAgent 用 Team Name 取得 Cloudflare 的公開金鑰驗證簽章，並核對 Application Audience (AUD) Tag。

5. MaiAgent 依憑證中的 Email 找到對應帳號（或依設定自動建立），成員即登入 MaiAgent。

事前準備

在 Cloudflare Zero Trust 端準備以下資訊：

項目	說明
Team Name	Zero Trust 的 team name。若團隊網域是 acme.cloudflareaccess.com，team name 就是 acme
Access Application	保護入口網址的 Access 應用程式。登入回呼的路徑是 /api/auth/cloudflare/<認證來源名稱>/callback/，這個路徑必須受該應用程式保護，並把請求轉送到 MaiAgent
AUD Tag	上述 Access Application 的 Application Audience (AUD) Tag

入口網址要怎麼把請求轉送到 MaiAgent，取決於貴組織的部署方式。設定前請先與 MaiAgent 窗口確認入口網址與轉送方式。

在 MaiAgent 設定

1. 從左側選單點選 組織設定 → 組織概覽，在 管理操作 區點選 第三方登入設定。

2. 在認證類型卡片中選擇 Cloudflare Access，下方會出現 Cloudflare Access 設定。

3. 填寫下表欄位後按 儲存，會跳出 確認變更認證方式，看過注意事項後按 確認變更。

欄位	必填	說明
認證來源名稱	是	用於識別此認證來源的唯一名稱，會成為登入連結的一部分。可用英文字母、數字、連字號（-）與底線（_），最多 31 個字元；不可使用 maiagent
伺服器 URL	是	受 Cloudflare Access 保護的入口網址，例如 https://portal.acme.com
Team Name	是	Cloudflare Zero Trust 的 team name，例如 acme
Application Audience (AUD) Tag	是	Access Application 的 AUD Tag
電子郵件網域	否	設定後，只有這個網域的信箱可以透過此認證來源登入，例如 acme.com。同一個網域不能同時被其他組織的認證來源使用
自動建立成員	否	預設關閉。行為見帳號對應

登入連結

儲存後，登入連結 區塊會產生 登入 URL，按複製後提供給成員，成員開啟這個連結就能透過 Cloudflare Access 登入。尚未儲存時，畫面會提示「請先儲存設定後，系統會自動產生登入連結」。

登入頁「輸入 Email 後自動導向單一登入」只適用於 SAML。使用 Cloudflare Access 的成員請直接使用登入連結，例如把它加入公司入口網站或書籤。

帳號對應

MaiAgent 以 Cloudflare 驗證後的 Email 對應帳號，並依 自動建立成員 決定是否放行：

情況	自動建立成員：關閉	自動建立成員：開啟
已經是本組織成員	登入	登入
有 MaiAgent 帳號，但不是本組織成員	拒絕登入	加入本組織後登入
還沒有 MaiAgent 帳號	拒絕登入	建立帳號並加入本組織後登入；顯示名稱預設為 Email 的 @ 前段
Email 不屬於設定的電子郵件網域	拒絕登入	拒絕登入

已經有 MaiAgent 帳號的成員，原本的登入方式（例如帳號密碼）仍然可以使用，Cloudflare Access 只是多一個登入入口。

登入失敗的訊息

畫面訊息	常見原因	處理方式
身分驗證失敗，請重新登入	請求沒有帶 Cloudflare 的身分憑證，或憑證驗證失敗（Team Name、AUD Tag 不符）	確認回呼路徑受 Access Application 保護，且兩個欄位與 Cloudflare 端一致
此帳號未被授權存取本組織	帳號不是本組織成員且未開啟自動建立成員，或 Email 不在設定的網域	先把成員加入組織，或開啟 自動建立成員
此登入方式目前已停用	這個認證來源的登入已被停用	請洽 MaiAgent 窗口
登入逾時，請重新登入	一次性的登入代碼已使用過或已逾時，例如重新整理了登入中的頁面	按 重新登入 再試一次
登入流程未完成，請重新登入	直接開啟了回呼頁面（沒有經過 Cloudflare 驗證），或流程中途中斷	從登入連結卡的網址重新開始

常見問題

Q：登出 MaiAgent 會一併登出 Cloudflare Access 嗎？

不會。登出只結束 MaiAgent 的登入狀態；Cloudflare Access 的登入狀態依貴公司在 Cloudflare 的工作階段設定而定。

Q：可以只讓特定網域的同事登入嗎？

可以。填寫 電子郵件網域 後，其他網域的信箱即使通過 Cloudflare 驗證也會被拒絕。更細的存取規則（例如只開放某些部門），請在 Cloudflare Access 的政策中設定。

Q：儲存時顯示「該信箱網域已被使用。」？

這個網域已經被其他認證來源使用，一個網域只能對應一個認證來源。請改用其他網域，或留空不限制。

延伸閱讀

• 第三方登入（SSO）：認證類型總覽、切換認證類型的影響

• 成員管理：事先把成員加入組織

• 角色權限管理：為登入的成員設定角色與權限