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

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

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

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

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

常見應用場景:

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

***

## 2. MaiAgent OAuth 整合架構

```mermaid
flowchart TD
    User["使用者"]
    Frontend["MaiAgent 前端"]
    Backend["MaiAgent 後端"]
    OAuth["第三方 OAuth 服務"]
    DB[("Token 儲存")]
    Celery["Celery 排程器"]
    
    User -- "1. 授權請求" --> Frontend
    Frontend -- "2. 重導向至授權頁面" --> OAuth
    OAuth -- "3. 使用者同意授權" --> OAuth
    OAuth -- "4. 回傳授權碼" --> Backend
    Backend -- "5. 交換 Access Token" --> OAuth
    OAuth -- "6. 返回 Token 資訊" --> Backend
    Backend -- "7. 加密儲存" --> DB
    Celery -- "8. 定期檢查 Token 過期" --> DB
    Celery -- "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 自動刷新機制

```mermaid
sequenceDiagram
    participant Celery as Celery Beat 排程器
    participant DB as Token 資料庫
    participant OAuth as OAuth 服務提供商
    participant Service as 第三方服務
    
    loop 每小時執行
        Celery->>DB: 查詢即將過期的 Token<br/>(剩餘時效 < 1 小時)
        DB-->>Celery: 返回待刷新 Token 列表
        
        loop 針對每個 Token
            Celery->>OAuth: 使用 Refresh Token<br/>請求新的 Access Token
            OAuth-->>Celery: 返回新的 Token 資訊
            Celery->>DB: 更新 Token 並記錄刷新時間
        end
    end
    
    Note over Celery,DB: 錯誤處理機制
    Celery->>DB: 記錄刷新失敗的 Token
    Celery->>Service: 通知管理員需要重新授權
```

**自動刷新機制的關鍵特性**:

1. **主動式刷新策略**: 在 Token 過期前主動刷新,避免服務中斷
2. **智慧查詢優化**: 僅查詢具備完整客戶端憑證的 Token,提升刷新效率
3. **錯誤處理與重試**: 針對刷新失敗的情況實施指數退避重試策略
4. **審計日誌**: 詳細記錄每次 Token 刷新的時間、結果和錯誤訊息

### 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
* **自動刷新時機**: 在 Token 到期前 1 小時自動刷新,確保服務不中斷
* **失敗通知**: 當 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/remote-mcp/remote-mcp.md) - 了解如何透過 OAuth 整合 Remote MCP 服務
* [Composio 串接](/tech/remote-mcp/composio.md) - Composio 平台的 OAuth 整合範例
* [Zapier 串接](/tech/remote-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: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/tech/advanced-genai-tech/oauth-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.