# 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/diagram content="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/diagram content="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 服務概述](https://docs.maiagent.ai/tech/remote-mcp/remote-mcp) - 了解如何透過 OAuth 整合 Remote MCP 服務
* [Composio 串接](https://docs.maiagent.ai/tech/remote-mcp/composio) - Composio 平台的 OAuth 整合範例
* [Zapier 串接](https://docs.maiagent.ai/tech/remote-mcp/zapier) - 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)