> 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/identity-and-access/maiagent-oauth-server.md).

# OAuth 認可サーバーとしての MaiAgent

Claude などの MCP クライアントを OAuth 2.1（認可コード＋PKCE）で MaiAgent MCP に接続するための、エンドポイント、アプリケーション登録、Redirect URI、トークンの有効期間とローテーション、および scope の実際の動作

MaiAgent は OAuth 2.1 認可サーバーを内蔵しています。Claude などの MCP クライアントは、設定ファイルに API Key を貼り付けずに、OAuth で MaiAgent MCP に接続できます。メンバーがブラウザーでログインして認可すると、クライアントは有効期間の短いアクセストークンを取得し、そのメンバーの権限で MaiAgent を操作します。本ページは、従業員が MCP クライアントから自分のアカウントで MaiAgent に接続できるようにしたいお客様の IT 担当者と、自社サービスからメンバーの権限で MaiAgent を呼び出したい開発者を対象としています。

{% hint style="info" %}
**ユーザーマニュアルとの役割分担**：管理画面の操作は、ユーザーマニュアルの [OAuth アプリケーション](https://docs.maiagent.ai/org/developer/oauth-applications)をご覧ください。MCP クライアントの接続設定（API Key と OAuth）は [MaiAgent MCP](/tech/ja/mcp/maiagent-mcp.md)をご覧ください。本ページでは、プロトコル仕様と連携時の要点のみを説明します。
{% endhint %}

本ページでは、MaiAgent がトークンを**発行する**場合を説明します。逆方向、つまり MaiAgent がサードパーティの OAuth サービスに接続する場合は、[OAuth 2.0 連携とトークンの自動更新](/tech/ja/advanced-genai-tech/oauth-integration.md)をご覧ください。

## OAuth と API Key の選び方 <a href="#oauth-or-api-key" id="oauth-or-api-key"></a>

| 項目             | OAuth（本ページ）                                                     | API Key                                                                                      |
| -------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| トークンやキーが表すユーザー | 認可したメンバー本人                                                      | キーに紐づくメンバー                                                                                   |
| 設定方法           | メンバーがブラウザーでログインして同意するため、シークレットを扱う必要はありません                       | キーをコピーしてクライアント設定に貼り付けます                                                                      |
| 有効期間           | アクセストークンは 1 時間で、クライアントが自動更新します                                  | キーの有効期限に従い、無期限にも設定できます                                                                       |
| 権限             | メンバーのロール権限と同じで、scope による追加の制限はありません（[scope の実際の動作](#scopes)を参照） | メンバーのロール権限と同じです                                                                              |
| キーの RPM 制限     | 適用されません                                                         | 適用されます。[API 共通仕様](https://docs.maiagent.ai/api/preparation/conventions#rate-limits)を参照してください |

SSO のみでログインし、MaiAgent のパスワードを持たないメンバーも、組織アカウントで OAuth 認可を完了できます。[ログインと同意](#login-and-consent)をご覧ください。

## エンドポイント <a href="#endpoints" id="endpoints"></a>

SaaS の認可サーバーは `https://api.maiagent.ai` です。オンプレミスやプライベートクラウドでは、自社のプラットフォームドメインに置き換えてください。メタデータ内の URL は、リクエストのドメインに応じて生成されます。

| 用途                    | メソッドとパス                                       |
| --------------------- | --------------------------------------------- |
| 認可サーバーメタデータ（RFC 8414） | `GET /.well-known/oauth-authorization-server` |
| 認可                    | `GET /o/authorize/`                           |
| トークンの取得・更新            | `POST /o/token/`                              |
| トークンの取り消し（RFC 7009）   | `POST /o/revoke_token/`                       |

メタデータで宣言される機能は以下のとおりで、実際の動作と一致しています。

| フィールド                                   | 値                                                 |
| --------------------------------------- | ------------------------------------------------- |
| `response_types_supported`              | `code`                                            |
| `grant_types_supported`                 | `authorization_code`、`refresh_token`              |
| `code_challenge_methods_supported`      | `S256`                                            |
| `token_endpoint_auth_methods_supported` | `none`、`client_secret_basic`、`client_secret_post` |
| `scopes_supported`                      | `read`、`write`                                    |

{% hint style="warning" %}
MaiAgent は**動的クライアント登録（Dynamic Client Registration）に対応していません**。メタデータに `registration_endpoint` はありません。MCP クライアントには、事前登録した Client ID を入力できる必要があります。まず次の節に従って、組織にアプリケーションを登録してください。
{% endhint %}

## 組織に OAuth アプリケーションを登録する <a href="#register-application" id="register-application"></a>

管理画面の <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">組織概要</mark> → <mark style="color:blue;">管理操作</mark> → <mark style="color:blue;">OAuth アプリケーション</mark> でアプリケーションを作成し、Client ID を取得します。ページの <mark style="color:blue;">接続情報</mark> カードには、Discovery、Authorize、Token の各エンドポイントが表示されます。作成手順、管理できるユーザー、Client Secret の保存と再生成については、ユーザーマニュアルの [OAuth アプリケーション](https://docs.maiagent.ai/org/developer/oauth-applications)をご覧ください。連携時には、以下の点に注意してください。

* **アプリケーションの種類は作成後に変更できません**：Public は MCP クライアント（Claude など）向けで、PKCE による認可を使用し、client secret は発行されません。Confidential はサーバー側の連携向けで、client secret が発行されます。
* Client Secret を再生成すると、古い secret は直ちに無効になりますが、発行済みのトークンには影響しません。アプリケーションを削除すると、それを通じて接続しているすべてのメンバーのトークンが直ちに無効になります。
* 各組織で作成できる OAuth アプリケーションは最大 20 個です。
* 同じ機能を API からも利用できます：`/api/v1/oauth/applications/`（GET、POST、PATCH、DELETE、および `POST …/{id}/regenerate-secret/`）。権限ルールは管理画面と同じです。

## Redirect URI のルール <a href="#redirect-uris" id="redirect-uris"></a>

* **完全一致**：スキーム、ホスト、ポート、パスがすべて一致する必要があり、ワイルドカードには対応していません。登録した URI にクエリパラメーターが含まれる場合、認可リクエストにも含める必要があります。
* `https://` のみを受け付けます。`http://` はローカルコールバックの `localhost`、`127.0.0.1`、`::1` に限り使用できます。
* ローカルコールバックのポート：`http://127.0.0.1/…` または `http://[::1]/…` を登録した場合、認可リクエストには任意のポートを使用できます（RFC 8252）。`http://localhost:<ポート>/…` を登録した場合、ポートは完全一致する必要があります。ローカル MCP クライアントが毎回ランダムにポートを選ぶ場合は、`127.0.0.1` の形式で登録してください。
* Web 版 MCP クライアントのコールバック URL は、そのクライアントのドキュメントに従ってください。管理画面のフォームにある例は `https://claude.ai/api/mcp/auth_callback` です。

## 認可フロー <a href="#authorization-flow" id="authorization-flow"></a>

MCP クライアントが MaiAgent MCP（SaaS では `https://mcp.maiagent.ai/mcp`）に接続する際の流れは、以下のとおりです。

1. クライアントが認証情報を付けずにリクエストすると、MCP サーバーは `401` を返します。`WWW-Authenticate` ヘッダーは `https://mcp.maiagent.ai/.well-known/oauth-protected-resource/mcp` を指します。
2. クライアントはこのリソースメタデータ（RFC 9728）を読み取ります。`authorization_servers` は `https://api.maiagent.ai` を指しており、続いて認可サーバーメタデータを読み取ります。
3. クライアントがブラウザーで `/o/authorize/` を開き、メンバーがログインして同意します。
4. MaiAgent は認可コードを Redirect URI に返し、クライアントは `code_verifier` を `/o/token/` に送信してトークンを取得します。
5. 以降の各呼び出しには `Authorization: Bearer <access_token>` を付けます。アクセストークンの期限が切れるか取り消されると、MCP サーバーは `401` を返し、クライアントはリフレッシュトークンで新しいトークンを取得します。

クライアントを独自に実装する場合、認可リクエストとトークン取得リクエストの形式は以下のとおりです。

```http
GET /o/authorize/?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&code_challenge=<CODE_CHALLENGE>&code_challenge_method=S256&state=<STATE>
```

```bash
curl -X POST https://api.maiagent.ai/o/token/ \
  -d grant_type=authorization_code \
  -d code=<CODE> \
  -d redirect_uri=<REDIRECT_URI> \
  -d client_id=<CLIENT_ID> \
  -d code_verifier=<CODE_VERIFIER>
```

* **PKCE は常に必須**です。Public と Confidential のどちらも同じで、`code_challenge_method` には `S256` を使用します。
* Confidential アプリケーションでは、さらに HTTP Basic（`client_secret_basic`）またはフォームフィールド `client_secret`（`client_secret_post`）で secret を送信します。
* 認可コードの有効期間は 300 秒です。
* トークン取得レスポンスには、`access_token`、`token_type`（`Bearer`）、`expires_in`（`3600`）、`refresh_token`、`scope` が含まれます。

### ログインと同意 <a href="#login-and-consent" id="login-and-consent"></a>

* 認可ページでは引き続き Email とパスワードでログインできます。認可を続行する際には、<mark style="color:blue;">組織アカウント（SSO）でログイン</mark> も利用できます。この入口では管理画面でログインを完了した後、認可ページに戻るため、SSO のみを使用し、MaiAgent のパスワードを持たないメンバーも認可できます。
* 同意ページには、アプリケーション名、所属組織、現在ログインしているメンバーの Email が表示されます。
* メンバーがそのアプリケーションの有効なトークンをすでに持っている場合、再接続時には同意ページが省略されます。

### SSO ログインの引き継ぎとセキュリティ境界 <a href="#sso-login-handoff" id="sso-login-handoff"></a>

例えば、企業の従業員が普段は SAML で MaiAgent にログインし、MaiAgent のパスワードを別途設定していない場合です。Claude などの MCP クライアントが認可ページを開くと、従業員は組織アカウントでのログインを選び、通常の管理画面へのログインを完了して認可ページに戻り、クライアントが自分の権限で接続することに同意します。

SSO の引き継ぎはブラウザーのログインフローであり、クライアントの認可コードと PKCE の交換を置き換えるものではありません。クライアントは引き続き上記の認可・トークンエンドポイントを使用し、管理画面のログイン引き継ぎコードを自ら処理する必要はありません。連携側では、以下の点に注意してください。

* 管理画面が受け取る署名付きログインリクエストの有効期間は 10 分です。ログイン完了後に使用するワンタイム引き継ぎコードは 300 秒間有効で、交換できるのは 1 回だけです。この引き継ぎコードは、MCP クライアントが取得する OAuth 認可コードとは用途が異なります。
* 引き継ぎコードはログインを開始したブラウザーに紐づき、このサイトの `/o/authorize/` のみを続行します。別のブラウザーでは使用できず、ログイン後のリダイレクト先に外部サイトを指定することもできません。
* アカウントが無効化されている場合や、その SSO 認証元でログインが無効になっている場合、引き継ぎは完了できません。メンバーが明示的にログアウトすると、ログアウト前に未完了だったログイン試行も無効になります。
* API Key やメンバー埋め込み用トークンを、ログイン引き継ぎコードに交換することはできません。これらで、メンバーがブラウザーで行うログインと認可を代替することはできません。

{% hint style="warning" %}
ログインの引き継ぎが未完了、タイムアウト、または無効になった場合は、認可ログインページからやり直してください。古い引き継ぎコードを再送信しないでください。
{% endhint %}

### トークンが表すユーザーと所属組織 <a href="#token-identity" id="token-identity"></a>

* トークンは認可したメンバーを表し、組織は**アプリケーションが所属する組織**に固定されます。呼び出し時に `X-Organization-Id` ヘッダーは不要で、このヘッダーに依存しません。
* 呼び出し時点で、そのユーザーが当該組織の有効なメンバーである必要があります。メンバーが無効化された、組織から削除された、または組織が削除された場合、トークンは直ちに使用できなくなり、API は `401` を返します。
* アクセストークンでプラットフォームの REST API を直接呼び出すこともできます（`Authorization: Bearer <access_token>`）。権限判定は API Key と同じです。例外として、AI Gateway の OpenAI 互換エンドポイントは API Key のみを受け付け、自分のアカウント削除などのリスクが高い操作は対話型ログインのみを受け付けます。

## トークンの有効期間とローテーション <a href="#token-lifetime" id="token-lifetime"></a>

| 項目              | ルール                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| 認可コード           | 300 秒                                                                                                      |
| アクセストークン        | 3600 秒（1 時間）                                                                                               |
| リフレッシュトークン      | 使用するたびにローテーションされます。レスポンスに新しいリフレッシュトークンが含まれ、古いものは無効になります                                                    |
| ローテーション後の再送信    | ネットワークや並行処理のために同じリクエストを再送信する場合、直前にローテーションされた古いリフレッシュトークンは 120 秒間使用できます                                     |
| 明示的な取り消し        | 直ちに適用され、120 秒の猶予期間はありません                                                                                   |
| リフレッシュトークンの有効期間 | 各リフレッシュトークンは発行から 30 日間有効です。更新に成功するたびに新しいトークンへローテーションされ、新しいトークンの発行時刻から 30 日間を再計算します。期限までに更新しなかった場合、再認可が必要です |

連携側で `invalid_grant` を受け取った場合は、そのリフレッシュトークンの使用を停止し、メンバーに再認可を案内してください。バックグラウンドで再試行しないでください。取り消しとローテーションの詳細は、[リフレッシュトークンが取り消された、または無効になった場合](#refresh-token-revocation)をご覧ください。

取り消し方法は 3 つあります。

| 取り消す人  | 方法                                                                                                                               | 影響範囲                             |
| ------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| 連携側    | `POST /o/revoke_token/` に `token`（任意で `token_type_hint`）とクライアント認証を送信します                                                          | 単一のトークン                          |
| メンバー本人 | `GET /api/v1/oauth/authorized-applications/` で自分が認可したアプリケーションを一覧表示し、`DELETE /api/v1/oauth/authorized-applications/{id}/` で取り消します | そのメンバーが当該アプリケーションに付与したすべてのトークン   |
| 組織管理者  | OAuth アプリケーションを削除します                                                                                                             | すべてのメンバーが当該アプリケーションに付与したすべてのトークン |

### リフレッシュトークンが取り消された、または無効になった場合 <a href="#refresh-token-revocation" id="refresh-token-revocation"></a>

リフレッシュトークンが明示的に取り消されると、直ちにアクセストークンの取得に使用できなくなります。連携側が引き続きそのトークンを `POST /o/token/` に送信すると、HTTP 400 とエラーコード `invalid_grant` が返されます。連携側では、以下のように対応してください。

1. `invalid_grant` を受け取ったら、そのリフレッシュトークンの使用を停止し、メンバーに再認可を案内してください。バックグラウンドで再試行しないでください。
2. メンバーが認可済みアプリケーション全体を取り消すと、そのメンバーが当該アプリケーションに付与したすべてのトークンが取り消され、古いリフレッシュトークンはすべて使用できなくなります。
3. 通常のローテーション後に、ネットワークや並行処理のために同じリクエストを再送信する場合、直前にローテーションされた古いリフレッシュトークンには 120 秒の再試行猶予があります。この猶予は明示的な取り消しには適用されません。

{% hint style="warning" %}
`invalid_grant` は再認可が必要であることを示すものとして扱ってください。明示的に取り消した後も 120 秒間使用できると考えないでください。30 日間の有効期間は上限であり、期間内の利用を保証するものではありません。取り消し、アプリケーションの削除、メンバーの無効化によって、認可が期限より早く無効になる場合があります。
{% endhint %}

## scope の実際の動作 <a href="#scopes" id="scopes"></a>

認可サーバーは `read` と `write` の 2 つの scope を受け付けます。認可リクエストで `scope` を指定しない場合、デフォルトで両方が付与されます。**現在、scope はどの API も制限しません**。実行できる操作は、メンバーのロール権限のみで決まり、そのメンバーが管理画面にログインした場合や API Key を使用した場合と同じです。MCP クライアントが実行できる操作を制限するには、そのユーザー向けに専用のロールを作成してください。ユーザーマニュアルの [ロールと権限の管理](https://docs.maiagent.ai/org/roles/role-permission)をご覧ください。

## よくある質問 <a href="#faq" id="faq"></a>

<details>

<summary>MCP クライアントで登録エンドポイントが見つからない、または登録できない場合は？</summary>

MaiAgent は動的クライアント登録に対応していません。まず <mark style="color:blue;">OAuth アプリケーション</mark> でアプリケーションを作成し、MCP クライアントの OAuth 設定に Client ID（Confidential の場合は Client Secret も）を入力してください。

</details>

<details>

<summary>認可時に redirect_uri の不一致が発生する場合は？</summary>

Redirect URI は完全一致で照合します。スキーム、ホスト、ポート、パスが登録値と完全に一致していることを確認してください。ローカルクライアントが毎回ポートを変える場合は、`http://127.0.0.1/…` の形式で登録してください。

</details>

<details>

<summary>しばらく接続した後に再認可を求められる場合は？</summary>

リフレッシュトークンが発行から 30 日を超えて更新されていない、または取り消されている場合、トークンエンドポイントは `invalid_grant` を返します。クライアントはメンバーに再認可を依頼する必要があります。メンバーが無効化されると、アクセストークンによる API 呼び出しは拒否されます（HTTP 401）。client secret を再生成しても、発行済みのトークンは無効になりません。

</details>


---

# 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/identity-and-access/maiagent-oauth-server.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.