OAuth 應用程式

在組織建立 OAuth 應用程式，讓 Claude 等 MCP 客戶端用 OAuth 授權連上 MaiAgent MCP，成員不必把 API Key 貼進設定檔；含建立、重新產生 Secret、端點資訊與每組織上限。

OAuth 應用程式讓 Claude 等 MCP 客戶端以標準 OAuth 2.1 授權流程連上 MaiAgent MCP。管理員先在組織建立一個應用程式、取得 Client ID；成員在 MCP 客戶端填入 Client ID 後，於瀏覽器登入 MaiAgent 並按「授權」即可完成連線，不需要把 API Key 貼進設定檔。

和 API Key 的差別：

項目	OAuth 應用程式	API Key
成員要做的事	在瀏覽器登入並按「授權」	建立金鑰並貼進客戶端設定檔或標頭
以誰的身分操作	完成授權的成員	金鑰綁定的成員
操作哪個組織	應用程式所屬的組織	金鑰所屬的組織
憑證有效期	存取權杖 1 小時，客戶端會自動續期；授權被撤銷、應用程式被刪除或成員被停用時需重新授權	依金鑰的到期時間
一次收回	刪除應用程式，所有成員的授權立即失效	逐把撤銷金鑰

兩種方式的操作權限都依成員自己的角色權限決定。API Key 的管理方式見 API Key 管理。

誰可以使用

操作	需要的條件
進入 OAuth 應用程式 頁面，查看應用程式列表與 連線資訊	角色權限 組織概覽權限
建立、編輯、刪除應用程式，重新產生 Client Secret	角色權限 組織權限 底下的「OAuth 應用程式管理權限」（組織擁有者預設具備；設定方式見編輯角色權限）
透過應用程式授權 MCP 客戶端	應用程式所屬組織的有效成員，且能以密碼登入 MaiAgent（見只用 SSO 登入的成員）

沒有管理權限的成員進入頁面後只能檢視：編輯圖示會換成檢視（眼睛）圖示，刪除按鈕無法點選。

進入方式

從左側選單點選 組織設定 → 組織概覽，在 管理操作 區點選 OAuth 應用程式。

頁面上方是 連線資訊，提供 MCP 客戶端設定時需要的三個端點，每個都可按 複製：

端點	用途
Discovery 端點	支援 OAuth 2.0 Authorization Server Metadata 的客戶端，可從這裡自動取得其他端點
授權端點（Authorize）	成員登入並授權的頁面
Token 端點	客戶端交換與續期存取權杖

授權流程必須使用 PKCE（S256）；Redirect URI 採完全比對，不支援萬用字元。

下方的應用程式列表欄位包含 名稱、Client ID、類型、已授權成員（已透過此應用程式授權的成員數）與 建立時間。

建立應用程式

1. 點選 建立應用程式，開啟 建立 OAuth 應用程式 視窗。

2. 填寫 名稱，例如 Claude。

3. 選擇 應用程式類型（建立後不可變更，需要變更時請刪除後重新建立）：

   類型	適用情境
   Public	MCP 客戶端（如 Claude），使用 PKCE 授權，不核發 Client Secret
   Confidential	伺服器端整合，會核發 Client Secret

4. 填寫 Redirect URIs：授權完成後允許導回的網址，例如 Claude 的 https://claude.ai/api/mcp/auth_callback。需要多個網址時按 新增 Redirect URI。只接受 https://；http:// 僅限本機開發用的 localhost、127.0.0.1、::1。

5. 按確認建立後，畫面會顯示 Client ID；Confidential 應用程式另會顯示 Client Secret。

Client Secret 只會顯示這一次，關閉後無法再取得。請複製保存後再按 我已保存，關閉；忘記保存時只能重新產生 Secret。

每個組織最多可建立 20 個 OAuth 應用程式。達到上限時，建立應用程式 按鈕會無法點選，並提示「已達組織 OAuth 應用程式上限（20 個）」。

讓成員用 OAuth 連上 MaiAgent MCP

1. 管理員把應用程式的 Client ID（Confidential 另附 Client Secret）與 MaiAgent MCP 的服務端點（見 MaiAgent MCP）提供給成員。

2. 成員在 MCP 客戶端新增自訂連接器：伺服器網址填 MaiAgent MCP 的服務端點，OAuth 設定填入 Client ID（與 Client Secret）。客戶端的 Redirect URI 必須和應用程式登記的完全相同。

3. 客戶端開啟瀏覽器，成員以公司信箱與密碼登入 MaiAgent。組織啟用 LDAP 帳密登入時，密碼為企業密碼。

4. 授權頁會顯示「授權 應用程式名稱？」、目前登入的帳號，以及這個應用程式所屬的組織。確認無誤後按「授權」。

5. 回到 MCP 客戶端，連線即完成。之後重新連線時，只要授權仍然有效，就不會再出現授權頁。

透過 OAuth 連線後，所有操作都作用在應用程式所屬的組織，權限與該成員在組織中的角色權限相同。成員若同時屬於多個組織，要操作哪個組織，就使用那個組織建立的應用程式。

只用 SSO 登入的成員

授權頁的登入畫面只提供 Email 與密碼，沒有 SSO 登入按鈕。只用 SSO 登入、沒有 MaiAgent 密碼的成員，目前無法完成授權，請改用 API Key 連線 MaiAgent MCP。

管理應用程式

編輯

點選列表的編輯圖示，可以修改 名稱 與 Redirect URIs；應用程式類型 不能修改。視窗上方會顯示 Client ID，可直接複製。

重新產生 Secret

只有 Confidential 應用程式有 Client Secret。在編輯視窗按 重新產生 Secret 並確認後：

• 舊的 Client Secret 立即失效，請更新所有使用它的伺服器端設定。

• 已連線的成員不受影響，只影響之後的權杖交換。

• 新的 Client Secret 同樣只顯示一次。

刪除

點選列表的刪除圖示並確認後，所有透過此應用程式連線的成員，其權杖會立即全部失效，這個操作無法復原。成員之後需要改用其他應用程式重新授權。

常見問題

Q：建立應用程式 按鈕無法點選？

可能有兩個原因：您沒有「OAuth 應用程式管理權限」（游標移到按鈕上會提示「您沒有 OAuth 應用程式管理權限，請聯絡組織管理者」），或組織已有 20 個應用程式。

Q：Redirect URI 存不進去？

只接受 https:// 網址；http:// 只能用在 localhost、127.0.0.1、::1。網址必須和 MCP 客戶端實際導回的網址完全一致，包含路徑與連接埠。

Q：連上後找不到預期的 Agent 或知識庫？

OAuth 連線操作的是應用程式所屬的組織。請確認成員使用的 Client ID 來自正確的組織，且成員在該組織的角色有權限存取這些資源。

Q：忘記保存 Client Secret？

系統無法再次顯示。請在編輯視窗按 重新產生 Secret 取得新的 Secret，並更新伺服器端設定。