> 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/tech/advanced-genai-tech/oauth-integration.md).

# OAuth 2.0 整合與 Token 自動刷新機制

OAuth 2.0 整合與 Token 自動刷新：MaiAgent 連接 Google Workspace、Salesforce、GitHub 等第三方服務的授權架構、refresh token 管理與最佳實踐。

> 本文件說明 MaiAgent 平台如何整合 OAuth 2.0 身分驗證協定,並提供自動化的 Token 刷新機制,確保第三方服務整合的安全性與持續可用性。

## 1. 為何需要 OAuth 整合？

MaiAgent 作為企業級 Agent 平台,需要與各種第三方服務(如 Google Workspace、Salesforce、GitHub 等)進行深度整合。OAuth 2.0 提供了標準化且安全的授權機制,解決了以下關鍵挑戰:

| 考量面向      | 傳統密碼儲存方案            | OAuth 2.0 授權方案                       |
| --------- | ------------------- | ------------------------------------ |
| **安全性**   | 需要儲存使用者的帳號密碼,存在洩漏風險 | 不需要儲存使用者密碼,使用短期存取權杖                  |
| **權限控制**  | 通常是完整帳號權限,無法細分      | 可精確控制授權範圍 (Scope),例如僅讀取 Gmail 或僅管理日曆 |
| **撤銷機制**  | 需要變更密碼才能撤銷存取        | 可隨時撤銷特定應用程式的存取權,不影響其他服務              |
| **使用者體驗** | 需要在第三方平台輸入密碼        | 在可信任的原生介面完成授權,體驗更流暢                  |

常見應用場景:

* **工具連接器 (Tool Connector)**: Agent 透過 OAuth 授權存取 Google Drive、Notion、Slack 等服務,執行檔案讀取、訊息發送等操作
* **資料同步**: 自動從 CRM 系統(如 Salesforce)同步客戶資料,無需手動匯入
* **自動化工作流程**: 整合專案管理工具(如 Jira、Asana),由 Agent 協助建立任務、更新狀態

***

## 2. MaiAgent OAuth 整合架構

```mermaid
flowchart TD
    User["使用者"]
    Frontend["MaiAgent 前端"]
    Backend["MaiAgent 後端"]
    OAuth["第三方 OAuth 服務"]
    DB[("Token 儲存")]
    Scheduler["排程任務"]
    
    User -- "1. 授權請求" --> Frontend
    Frontend -- "2. 重導向至授權頁面" --> OAuth
    OAuth -- "3. 使用者同意授權" --> OAuth
    OAuth -- "4. 回傳授權碼" --> Backend
    Backend -- "5. 交換 Access Token" --> OAuth
    OAuth -- "6. 返回 Token 資訊" --> Backend
    Backend -- "7. 加密儲存" --> DB
    Scheduler -- "8. 每 20 分鐘檢查即將到期的 Token" --> DB
    Scheduler -- "9. 自動刷新 Token" --> OAuth
```

### 2.1 授權流程優化

MaiAgent 實作了以下關鍵優化:

* **狀態驗證 (State Validation)**: 每次授權請求都會生成唯一的 state 參數,防止 CSRF 攻擊
* **成員層級授權**: 支援組織成員個別進行 OAuth 授權,實現更精細的權限管理
* **靈活的回調處理**: connector\_id 參數設為可選,支援組織層級或成員層級的授權模式
* **Access Token 驗證**: 在 Token 回應中強制驗證 access\_token 的存在性,確保授權流程完整性

### 2.2 Token 安全儲存

MaiAgent 採用多層次的安全措施保護 OAuth Token:

* **加密儲存**: 所有 Token (Access Token、Refresh Token) 在儲存前都經過加密處理
* **客戶端憑證管理**: 儲存 OAuth 應用程式的 client\_id 和 client\_secret,用於 Token 刷新
* **Token 元資料**: 記錄 Token 的到期時間、授權範圍、關聯的使用者和連接器資訊
* **舊版 Token 處理**: 自動排除沒有客戶端憑證的舊版 Token,確保系統僅使用可自動刷新的 Token

### 2.3 Token 自動刷新機制

存取權杖（Access Token）有效期限通常很短。MaiAgent 用兩種方式在權杖到期前換發新權杖，讓 Agent 與連接器不必每次都請使用者重新授權：**定期刷新**與**使用時刷新**。

```mermaid
sequenceDiagram
    participant Scheduler as 排程任務
    participant DB as Token 資料庫
    participant OAuth as OAuth 服務提供商

    loop 每 20 分鐘
        Scheduler->>DB: 查詢已過期或 30 分鐘內到期、<br/>且近 7 天活躍的權杖（每次最多 50 筆）
        DB-->>Scheduler: 待刷新權杖清單
        loop 逐筆處理
            Scheduler->>OAuth: 以 Refresh Token 換發新的 Access Token
            alt 換發成功
                OAuth-->>Scheduler: 新的權杖資訊
                Scheduler->>DB: 更新權杖與到期時間
            else 授權伺服器回應 400／401
                Scheduler->>DB: 停用這筆授權（需重新授權）
            else 其他錯誤
                Scheduler->>DB: 保留原狀，下一次排程再試
            end
        end
    end
```

#### 定期刷新的規則 <a href="#scheduled-refresh-rules" id="scheduled-refresh-rules"></a>

| 項目                    | 規則                                                          |
| --------------------- | ----------------------------------------------------------- |
| 執行頻率                  | 每 20 分鐘一次                                                   |
| 刷新對象                  | 已過期，或 30 分鐘內就會到期的權杖                                         |
| 涵蓋範圍                  | 成員授權的連接器、成員授權的 MCP 工具，以及聯絡人授權的連接器                           |
| 活躍條件                  | 成員的權杖：近 7 天內有更新，且成員與所屬組織都仍有效；聯絡人的權杖：近 7 天內使用過（從未使用過的以授權時間計） |
| 必要條件                  | 權杖附有 Refresh Token，且保存了 OAuth Client ID；連接器或工具已停用時略過        |
| 每次處理量                 | 最多 50 筆，依到期時間先後處理；同一時間只會有一個刷新任務在執行                          |
| 單筆換發失敗                | 記錄錯誤，不在同一次執行中重試；仍符合條件時，由下一次排程再試                             |
| 整個任務執行失敗              | 固定間隔 60 秒後重試，最多 3 次                                         |
| 授權伺服器拒絕（HTTP 400／401） | 這筆授權會被停用，使用者需要重新授權                                          |
| 回應沒有新的 Refresh Token  | 沿用原本的 Refresh Token                                         |

超過 7 天沒有活動的權杖不會被定期刷新；成員停用或離開組織後，他的權杖也不再刷新。之後再使用時，會依下方的「使用時刷新」處理；若 Refresh Token 已失效，需要重新授權。

#### 使用時刷新 <a href="#on-use-refresh" id="on-use-refresh"></a>

Agent 要使用權杖時，若權杖已過期或 60 秒內就會到期，平台會先換發新權杖再呼叫；換發失敗時，這次呼叫拿不到權杖。連接器的授權換發失敗後，會暫停一段時間不再嘗試：從 60 秒開始，每次失敗加倍，最長 1 小時。MCP 工具的權杖（成員授權或組織共用）也在使用前依同樣的 60 秒規則換發。

### 2.4 成員層級授權支援

MaiAgent 現在支援更精細的成員層級 OAuth 授權:

* **獨立授權流程**: 每個組織成員可以獨立完成 OAuth 授權,無需組織管理員介入
* **授權元資料**: 在 OAuth state 中包含成員相關的上下文資訊,實現授權流程的準確追蹤
* **重導向 URI 簡化**: 優化 OAuth 回調 URI 結構,提升整合的靈活性和可維護性
* **前端狀態管理**: 使用 sessionStorage 管理成員 OAuth 重導向邏輯,確保授權流程的連續性

***

## 3. OAuth 整合最佳實踐

### 3.1 授權範圍 (Scope) 設計原則

在配置 OAuth 應用程式時,應遵循「最小權限原則」:

* **僅申請必要權限**: 如果只需要讀取 Google Calendar,不要申請 Gmail 的寫入權限
* **明確告知使用者**: 在授權前清楚說明為何需要這些權限
* **支援增量授權**: 當需要額外權限時,再次引導使用者進行授權

### 3.2 Token 生命週期管理

MaiAgent 的 Token 管理遵循以下最佳實踐:

* **Access Token**: 短期有效(通常 1 小時),用於實際的 API 呼叫
* **Refresh Token**: 長期有效(可能數月至永久),用於獲取新的 Access Token
* **自動刷新時機**: 每 20 分鐘檢查一次，刷新 30 分鐘內到期的權杖；使用時若 60 秒內到期也會先刷新，規則見 [2.3](#scheduled-refresh-rules)
* **Refresh Token 失效**: 授權伺服器拒絕換發時，該筆授權會被停用，使用者需要重新授權

### 3.3 安全性考量

* **HTTPS 強制**: 所有 OAuth 相關的通訊都必須透過 HTTPS 進行
* **State 參數驗證**: 防止 CSRF 攻擊,確保授權請求的完整性
* **Token 加密儲存**: 使用業界標準的加密演算法保護敏感資料
* **定期審計**: 記錄所有 Token 的使用情況,便於安全審查

***

## 4. MaiAgent OAuth 整合的技術優勢

### 4.1 開發整合優勢

* **標準化介面**: 遵循 OAuth 2.0 標準,相容絕大多數第三方服務
* **簡化配置**: 管理員只需提供 OAuth 應用程式的基本資訊,即可完成整合
* **自動化維護**: Token 刷新完全自動化,無需人工介入
* **彈性部署**: 支援組織層級和成員層級的多種授權模式

### 4.2 安全性與合規優勢

* **零密碼儲存**: 完全避免儲存使用者密碼的安全風險
* **精細權限控制**: 可針對不同服務設定不同的授權範圍
* **即時撤銷**: 管理員或使用者可隨時撤銷授權,變更立即生效
* **審計追蹤**: 完整記錄所有授權和 Token 使用活動

### 4.3 使用者體驗優勢

* **無感刷新**: Token 自動刷新對使用者完全透明,不影響使用體驗
* **流暢授權**: 在可信任的原生介面完成授權,無需擔心密碼洩漏
* **持續可用**: 只要 Refresh Token 有效,服務就能持續運作

***

## 5. 相關技術文檔

* [Remote MCP 服務概述](/tech/mcp/remote-mcp.md) - 了解如何透過 OAuth 整合 Remote MCP 服務
* [Composio 串接](/tech/mcp/composio.md) - Composio 平台的 OAuth 整合範例
* [Zapier 串接](/tech/mcp/zapier.md) - Zapier 平台的 OAuth 整合指南

### 參考連結

* [OAuth 2.0 RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)
* [OAuth 2.0 Security Best Current Practice](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics)
* [PKCE for OAuth Public Clients (RFC 7636)](https://datatracker.ietf.org/doc/html/rfc7636)


---

# 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/tech/advanced-genai-tech/oauth-integration.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.