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

# OAuth 2.0 連携とトークンの自動更新

OAuth 2.0 連携とトークンの自動更新：MaiAgent を Google Workspace、Salesforce、GitHub などの外部サービスに接続するための認可アーキテクチャ、Refresh Token の管理、ベストプラクティスを説明します。

> 本ドキュメントでは、MaiAgent プラットフォームが OAuth 2.0 認証プロトコルと連携し、トークンを自動更新することで、外部サービスとの連携の安全性と継続的な利用を確保する仕組みを説明します。

## 1. OAuth 連携が必要な理由

MaiAgent はエンタープライズ向け Agent プラットフォームとして、Google Workspace、Salesforce、GitHub など、さまざまな外部サービスとの密接な連携を必要とします。OAuth 2.0 は標準化された安全な認可の仕組みを提供し、以下の主要な課題を解決します。

| 検討事項         | 従来のパスワード保存方式                            | OAuth 2.0 認可方式                                     |
| ------------ | --------------------------------------- | -------------------------------------------------- |
| **セキュリティ**   | ユーザーのアカウントとパスワードを保存する必要があり、漏えいのリスクがあります | ユーザーのパスワードを保存せず、有効期間の短いアクセストークンを使用します              |
| **権限制御**     | 通常はアカウントの全権限を使用し、細かく分けられません             | Gmail の読み取りのみ、カレンダーの管理のみなど、認可スコープ（Scope）を細かく制御できます |
| **取り消しの仕組み** | アクセスを取り消すにはパスワードの変更が必要です                | 他のサービスに影響を与えず、特定のアプリケーションのアクセス権をいつでも取り消せます         |
| **ユーザー体験**   | 外部プラットフォームでパスワードを入力する必要があります            | 信頼できるサービス本来の画面で認可を完了でき、よりスムーズに利用できます               |

一般的な利用例は以下のとおりです。

* **ツールコネクタ（Tool Connector）**：Agent が OAuth 認可を通じて Google Drive、Notion、Slack などにアクセスし、ファイルの読み取りやメッセージ送信などの操作を行います
* **データ同期**：Salesforce などの CRM システムから顧客データを自動同期し、手動インポートを不要にします
* **ワークフローの自動化**：Jira、Asana などのプロジェクト管理ツールと連携し、Agent がタスク作成やステータス更新を支援します

***

## 2. MaiAgent の OAuth 連携アーキテクチャ

```mermaid
flowchart TD
    User["ユーザー"]
    Frontend["MaiAgent フロントエンド"]
    Backend["MaiAgent バックエンド"]
    OAuth["外部 OAuth サービス"]
    DB[("トークンの保存")]
    Scheduler["スケジュールタスク"]

    User -- "1. 認可リクエスト" --> Frontend
    Frontend -- "2. 認可ページへリダイレクト" --> OAuth
    OAuth -- "3. ユーザーが認可に同意" --> OAuth
    OAuth -- "4. 認可コードを返却" --> Backend
    Backend -- "5. Access Token と交換" --> OAuth
    OAuth -- "6. トークン情報を返却" --> Backend
    Backend -- "7. 暗号化して保存" --> DB
    Scheduler -- "8. 20 分ごとに期限切れが近いトークンを確認" --> DB
    Scheduler -- "9. トークンを自動更新" --> OAuth
```

### 2.1 認可フローの最適化

MaiAgent は以下の主要な最適化を実装しています。

* **状態検証（State Validation）**：認可リクエストごとに一意の state パラメータを生成し、CSRF 攻撃を防ぎます
* **メンバー単位の認可**：組織メンバーが個別に OAuth 認可を行えるため、より細かな権限管理が可能です
* **柔軟なコールバック処理**：connector\_id パラメータを任意とし、組織単位とメンバー単位の認可モードに対応します
* **Access Token の検証**：トークンレスポンスに access\_token が存在することを必須検証し、認可フローの完全性を確保します

### 2.2 トークンの安全な保存

MaiAgent は複数のセキュリティ対策で OAuth トークンを保護します。

* **暗号化保存**：すべてのトークン（Access Token、Refresh Token）を保存前に暗号化します
* **クライアント認証情報の管理**：OAuth アプリケーションの client\_id と client\_secret を保存し、トークン更新に使用します
* **トークンのメタデータ**：トークンの有効期限、認可スコープ、関連するユーザーとコネクタの情報を記録します
* **旧形式のトークンの処理**：クライアント認証情報のない旧形式のトークンを自動的に除外し、自動更新できるトークンのみを使用します

### 2.3 トークンの自動更新の仕組み

アクセストークン（Access Token）の有効期間は通常短く設定されています。MaiAgent は期限切れになる前に、**定期更新**と**使用時更新**の 2 つの方法で新しいトークンを取得するため、Agent やコネクタが毎回ユーザーに再認可を求める必要はありません。

```mermaid
sequenceDiagram
    participant Scheduler as スケジュールタスク
    participant DB as トークンデータベース
    participant OAuth as OAuth プロバイダー

    loop 20 分ごと
        Scheduler->>DB: 期限切れ、または 30 分以内に期限切れになる、<br/>直近 7 日間に活動があったトークンを検索（1 回につき最大 50 件）
        DB-->>Scheduler: 更新対象のトークン一覧
        loop 1 件ずつ処理
            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 分ごとに 1 回実行します                                                                             |
| 更新対象                          | 期限切れ、または 30 分以内に期限切れになるトークンです                                                                |
| 対象範囲                          | メンバーが認可したコネクタ、メンバーが認可した MCP ツール、および連絡先が認可したコネクタです                                            |
| 活動条件                          | メンバーのトークン：直近 7 日以内に更新され、メンバーと所属組織の両方が有効であること。連絡先のトークン：直近 7 日以内に使用されていること（未使用の場合は認可日時を基準にします） |
| 必須条件                          | Refresh Token があり、OAuth Client ID が保存されていること。無効化されたコネクタやツールはスキップします                          |
| 1 回の処理件数                      | 最大 50 件を有効期限順に処理します。同時に実行される更新タスクは 1 つだけです                                                   |
| 個別の更新失敗                       | エラーを記録し、同じ実行内では再試行しません。条件を満たしていれば、次回のスケジュール実行で再試行します                                         |
| タスク全体の実行失敗                    | 固定間隔の 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 トークンのライフサイクル管理

MaiAgent のトークン管理は、以下のベストプラクティスに従っています。

* **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 攻撃を防ぎ、認可リクエストの完全性を確保します
* **トークンの暗号化保存**：業界標準の暗号化アルゴリズムで機密データを保護します
* **定期監査**：すべてのトークン使用状況を記録し、セキュリティレビューに役立てます

***

## 4. MaiAgent の OAuth 連携の技術的な利点

### 4.1 開発・連携の利点

* **標準化されたインターフェース**：OAuth 2.0 標準に従い、大多数の外部サービスと互換性があります
* **設定の簡素化**：管理者が OAuth アプリケーションの基本情報を提供するだけで連携を完了できます
* **保守の自動化**：トークン更新は完全に自動化され、手動の対応は不要です
* **柔軟なデプロイ**：組織単位とメンバー単位の複数の認可モードに対応します

### 4.2 セキュリティ・コンプライアンスの利点

* **パスワードを保存しません**：ユーザーのパスワード保存によるセキュリティリスクを完全に回避します
* **細かな権限制御**：サービスごとに異なる認可スコープを設定できます
* **即時取り消し**：管理者またはユーザーがいつでも認可を取り消せ、変更は即座に反映されます
* **監査証跡**：すべての認可とトークン使用の活動を完全に記録します

### 4.3 ユーザー体験の利点

* **シームレスな更新**：トークンの自動更新はユーザーに意識させず、利用体験に影響しません
* **スムーズな認可**：信頼できるサービス本来の画面で認可を完了でき、パスワード漏えいを心配する必要がありません
* **継続的な利用**：Refresh Token が有効である限り、サービスを継続して利用できます

***

## 5. 関連技術ドキュメント

* [Remote MCP サービスの概要](/tech/ja/mcp/remote-mcp.md) - OAuth を通じた Remote MCP サービスとの連携方法を説明します
* [Composio 連携](/tech/ja/mcp/composio.md) - Composio プラットフォームの OAuth 連携例を紹介します
* [Zapier 連携](/tech/ja/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/ja/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.