> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/org/developer/oauth-applications.md).

# OAuth 應用程式

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

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

**和 API Key 的差別**：

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

兩種方式的操作權限都依成員自己的角色權限決定。API Key 的管理方式見 [API Key 管理](/org/developer/api-keys.md)。

## 誰可以使用 <a href="#permissions" id="permissions"></a>

| 操作                                                                                                | 需要的條件                                                                                                                                        |
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 進入 <mark style="color:blue;">OAuth 應用程式</mark> 頁面，查看應用程式列表與 <mark style="color:blue;">連線資訊</mark> | 角色權限 <mark style="color:blue;">組織概覽權限</mark>                                                                                                 |
| 建立、編輯、刪除應用程式，重新產生 Client Secret                                                                   | 角色權限 <mark style="color:blue;">組織權限</mark> 底下的「OAuth 應用程式管理權限」（組織擁有者預設具備；設定方式見[編輯角色權限](/org/roles/role-permission.md#edit-role-permissions)） |
| 透過應用程式授權 MCP 客戶端                                                                                  | 應用程式所屬組織的有效成員，且能以密碼登入 MaiAgent（見[只用 SSO 登入的成員](#sso-only-members)）                                                                           |

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

## 進入方式 <a href="#how-to-enter" id="how-to-enter"></a>

從左側選單點選 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">組織概覽</mark>，在 <mark style="color:blue;">管理操作</mark> 區點選 <mark style="color:blue;">OAuth 應用程式</mark>。

頁面上方是 <mark style="color:blue;">連線資訊</mark>，提供 MCP 客戶端設定時需要的三個端點，每個都可按 <mark style="color:blue;">複製</mark>：

| 端點                                               | 用途                                                           |
| ------------------------------------------------ | ------------------------------------------------------------ |
| <mark style="color:blue;">Discovery 端點</mark>    | 支援 OAuth 2.0 Authorization Server Metadata 的客戶端，可從這裡自動取得其他端點 |
| <mark style="color:blue;">授權端點（Authorize）</mark> | 成員登入並授權的頁面                                                   |
| <mark style="color:blue;">Token 端點</mark>        | 客戶端交換與續期存取權杖                                                 |

{% hint style="info" %}
授權流程必須使用 PKCE（S256）；Redirect URI 採完全比對，不支援萬用字元。
{% endhint %}

下方的應用程式列表欄位包含 <mark style="color:blue;">名稱</mark>、<mark style="color:blue;">Client ID</mark>、<mark style="color:blue;">類型</mark>、<mark style="color:blue;">已授權成員</mark>（已透過此應用程式授權的成員數）與 <mark style="color:blue;">建立時間</mark>。

## 建立應用程式 <a href="#create-application" id="create-application"></a>

1. 點選 <mark style="color:blue;">建立應用程式</mark>，開啟 <mark style="color:blue;">建立 OAuth 應用程式</mark> 視窗。
2. 填寫 <mark style="color:blue;">名稱</mark>，例如 `Claude`。
3. 選擇 <mark style="color:blue;">應用程式類型</mark>（建立後不可變更，需要變更時請刪除後重新建立）：

   | 類型                                            | 適用情境                                           |
   | --------------------------------------------- | ---------------------------------------------- |
   | <mark style="color:blue;">Public</mark>       | MCP 客戶端（如 Claude），使用 PKCE 授權，不核發 Client Secret |
   | <mark style="color:blue;">Confidential</mark> | 伺服器端整合，會核發 Client Secret                       |
4. 填寫 <mark style="color:blue;">Redirect URIs</mark>：授權完成後允許導回的網址，例如 Claude 的 `https://claude.ai/api/mcp/auth_callback`。需要多個網址時按 <mark style="color:blue;">新增 Redirect URI</mark>。只接受 `https://`；`http://` 僅限本機開發用的 `localhost`、`127.0.0.1`、`::1`。
5. 按確認建立後，畫面會顯示 <mark style="color:blue;">Client ID</mark>；Confidential 應用程式另會顯示 <mark style="color:blue;">Client Secret</mark>。

{% hint style="warning" %}
Client Secret 只會顯示這一次，關閉後無法再取得。請複製保存後再按 <mark style="color:blue;">我已保存，關閉</mark>；忘記保存時只能[重新產生 Secret](#regenerate-secret)。
{% endhint %}

每個組織最多可建立 20 個 OAuth 應用程式。達到上限時，<mark style="color:blue;">建立應用程式</mark> 按鈕會無法點選，並提示「已達組織 OAuth 應用程式上限（20 個）」。

## 讓成員用 OAuth 連上 MaiAgent MCP <a href="#connect-mcp-client" id="connect-mcp-client"></a>

1. 管理員把應用程式的 <mark style="color:blue;">Client ID</mark>（Confidential 另附 Client Secret）與 MaiAgent MCP 的服務端點（見 [MaiAgent MCP](https://docs.maiagent.ai/tech/mcp/maiagent-mcp#what-is-maiagent-mcp)）提供給成員。
2. 成員在 MCP 客戶端新增自訂連接器：伺服器網址填 MaiAgent MCP 的服務端點，OAuth 設定填入 Client ID（與 Client Secret）。客戶端的 Redirect URI 必須和應用程式登記的完全相同。
3. 客戶端開啟瀏覽器，成員以公司信箱與密碼登入 MaiAgent。組織啟用 LDAP 帳密登入時，密碼為企業密碼。
4. 授權頁會顯示「授權 應用程式名稱？」、目前登入的帳號，以及這個應用程式所屬的組織。確認無誤後按「授權」。
5. 回到 MCP 客戶端，連線即完成。之後重新連線時，只要授權仍然有效，就不會再出現授權頁。

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

### 只用 SSO 登入的成員 <a href="#sso-only-members" id="sso-only-members"></a>

授權頁的登入畫面只提供 Email 與密碼，沒有 SSO 登入按鈕。只用 SSO 登入、沒有 MaiAgent 密碼的成員，目前無法完成授權，請改用 [API Key](/org/developer/api-keys.md) 連線 MaiAgent MCP。

## 管理應用程式 <a href="#manage-applications" id="manage-applications"></a>

### 編輯 <a href="#edit-application" id="edit-application"></a>

點選列表的編輯圖示，可以修改 <mark style="color:blue;">名稱</mark> 與 <mark style="color:blue;">Redirect URIs</mark>；<mark style="color:blue;">應用程式類型</mark> 不能修改。視窗上方會顯示 <mark style="color:blue;">Client ID</mark>，可直接複製。

### 重新產生 Secret <a href="#regenerate-secret" id="regenerate-secret"></a>

只有 Confidential 應用程式有 Client Secret。在編輯視窗按 <mark style="color:blue;">重新產生 Secret</mark> 並確認後：

* 舊的 Client Secret 立即失效，請更新所有使用它的伺服器端設定。
* 已連線的成員不受影響，只影響之後的權杖交換。
* 新的 Client Secret 同樣只顯示一次。

### 刪除 <a href="#delete-application" id="delete-application"></a>

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

## 常見問題 <a href="#faq" id="faq"></a>

#### Q：<mark style="color:blue;">建立應用程式</mark> 按鈕無法點選？ <a href="#faq-create-disabled" id="faq-create-disabled"></a>

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

#### Q：Redirect URI 存不進去？ <a href="#faq-redirect-uri-invalid" id="faq-redirect-uri-invalid"></a>

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

#### Q：連上後找不到預期的 Agent 或知識庫？ <a href="#faq-wrong-organization" id="faq-wrong-organization"></a>

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

#### Q：忘記保存 Client Secret？ <a href="#faq-lost-secret" id="faq-lost-secret"></a>

系統無法再次顯示。請在編輯視窗按 <mark style="color:blue;">重新產生 Secret</mark> 取得新的 Secret，並更新伺服器端設定。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/org/developer/oauth-applications.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.