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

# 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/maiagent-tech-ja/remote-mcp/remote-mcp.md) - OAuth を通じて Remote MCP サービスを連携する方法について
* [Composio 連携](/tech/maiagent-tech-ja/remote-mcp/composio.md) - Composio プラットフォームの OAuth 連携例
* [Zapier 連携](/tech/maiagent-tech-ja/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
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 dynamically by asking a question.

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

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.