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 を呼び出す開発者を対象としています。

ユーザーマニュアルとの役割分担：管理画面での操作はユーザーマニュアルの OAuth アプリケーションを参照してください。MCP クライアントの接続設定（API Key と OAuth）は MaiAgent MCPを参照してください。本ページではプロトコル仕様と連携上の要点のみを説明します。

本ページでは MaiAgent がトークンを発行する場合を説明します。逆方向、つまり MaiAgent がサードパーティーの OAuth サービスに接続する場合は、OAuth 2.0 連携と Token 自動更新の仕組みを参照してください。

OAuth と API Key の選び方

項目	OAuth（本ページ）	API Key
表す ID	認可したメンバー本人です	キーに紐付けられたメンバーです
提供方法	メンバーがブラウザーでログインして同意します。秘密情報を扱う必要はありません	キーをコピーしてクライアント設定に貼り付けます
有効期間	アクセストークンは1時間有効で、クライアントが自動更新します	キーの有効期限に従います。無期限にも設定できます
権限	メンバーのロールと同じです。scope による追加制限はありません（scope の実際の作用を参照してください）	メンバーのロールと同じです
キーの RPM 制限	適用されません	適用されます。API 共通規約を参照してください

SSO のみでログインし、MaiAgent のパスワードを持たないメンバーは、現在 OAuth 認可を完了できません（ログインと同意を参照してください）。このようなメンバーには API Key を使用してください。

エンドポイント

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

MaiAgent は動的クライアント登録（Dynamic Client Registration）に対応していません。メタデータに registration_endpoint はありません。MCP クライアントは事前登録済みの Client ID を入力できる必要があります。まず次のセクションに従って組織内にアプリケーションを登録してください。

組織に OAuth アプリケーションを登録します

管理画面の 組織設定 → 組織概要 → 管理操作 → OAuth アプリケーション でアプリケーションを作成し、Client ID を取得します。ページの 接続情報 カードには Discovery、Authorize、Token エンドポイントが表示されます。作成手順、管理権限、Client Secret の保存・再生成については、ユーザーマニュアルの OAuth アプリケーションを参照してください。連携時は次の点に注意してください：

• アプリケーションの種類は作成後に変更できません：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 のルール

• 完全一致で照合します：scheme、ホスト、ポート、パスがすべて一致する必要があります。ワイルドカードには対応していません。登録した 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 です。

認可フロー

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 を返し、クライアントはリフレッシュトークンで新しいトークンを取得します。

クライアントを独自実装する場合、認可リクエストとトークン交換リクエストは次の形式です：

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

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 が含まれます。

ログインと同意

• 認可ページのログイン画面では Email とパスワードのみを使用できます。MaiAgent のパスワード、または組織が LDAP 認証を有効にしている場合は企業のパスワードを使用します。SSO ログインボタンはないため、SSO のみでログインし、パスワードを持たないアカウントは認可を完了できません。

• 同意ページには、アプリケーション名、所属組織、現在ログインしているメンバーの Email が表示されます。

• メンバーがすでにこのアプリケーションの有効なトークンを持っている場合、再接続時に同意ページをスキップします。

トークンが表すユーザーと所属組織

• トークンは認可したメンバーを表します。組織はアプリケーションが所属する組織に固定され、呼び出し時に X-Organization-Id ヘッダーは不要で、参照もされません。

• 呼び出し時点で、そのメンバーは組織の有効なメンバーである必要があります。メンバーが無効化・組織から削除された場合や、組織が削除された場合、トークンは即座に使用できなくなり、API は 401 を返します。

• アクセストークンでプラットフォームの REST API を直接呼び出すこともできます（Authorization: Bearer <access_token>）。権限判定は API Key と同じです。例外として、AI Gateway の OpenAI 互換エンドポイントは API Key のみ受け付けます。自分のアカウントの削除などの高リスク操作は対話型ログインのみ受け付けます。

トークンの有効期間とローテーション

項目	ルール
認可コード	300 秒です
アクセストークン	3600 秒（1時間）です
リフレッシュトークン	使用するたびにローテーションします。レスポンスに新しいリフレッシュトークンが含まれ、旧トークンは無効になります
ローテーション後の再送	ネットワークや並行処理により同じリクエストを再送する場合、直前にローテーションした旧リフレッシュトークンは 120 秒以内であれば使用できます
明示的な失効	即座に有効になり、120 秒の猶予はありません
リフレッシュトークンの有効期間	固定の有効期間に依存しないでください。失効、アプリケーションの削除、メンバーの無効化により使用できなくなります。トークンエンドポイントが invalid_grant を返すかどうかで判断してください

連携側で invalid_grant を受け取った場合は、そのリフレッシュトークンの使用を停止し、メンバーに再認可を案内してください。バックグラウンドで再試行しないでください。失効とローテーションの詳細はリフレッシュトークンが失効・無効化された場合を参照してください。

トークンを失効させる方法は3つあります：

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

リフレッシュトークンが失効・無効化された場合

リフレッシュトークンを明示的に失効させると、即座にアクセストークンとの交換に使用できなくなります。連携側が引き続きそのトークンを POST /o/token/ に送信すると、HTTP 400 とエラーコード invalid_grant が返ります。連携側では次のように処理してください：

1. invalid_grant を受け取ったら、そのリフレッシュトークンの使用を停止し、メンバーに再認可を案内してください。バックグラウンドで再試行しないでください。

2. メンバーが認可済みアプリケーション全体を取り消すと、そのメンバーがそのアプリケーションに付与したすべてのトークンが失効し、旧リフレッシュトークンはすべて使用できなくなります。

3. 通常のローテーション後、ネットワークや並行処理によって同じリクエストを再送する場合、直前にローテーションした旧リフレッシュトークンには 120 秒の再試行猶予があります。この猶予は明示的な失効には適用されません。

invalid_grant は再認可が必要であることを示します。明示的に失効させた後も 120 秒間使用できると考えないでください。また、リフレッシュトークンの固定の有効期間に基づいて再認可を予定しないでください。

scope の実際の作用

認可サーバーは read と write の2つの scope を受け付けます。認可リクエストで scope を省略した場合は、デフォルトで両方を付与します。現在、scope はどの API も制限しません。実行できる操作はすべてメンバーのロール権限で決まり、管理画面へのログインや API Key の使用時と同じです。MCP クライアントが実行できる操作を制限するには、そのユーザー向けに専用ロールを設計してください。ユーザーマニュアルのロール権限管理を参照してください。

よくある質問

MCP クライアントで登録エンドポイントが見つからない、または登録できないと表示されますか？

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

認可時に redirect_uri の不一致が表示されますか？

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

接続してしばらくすると再認可を求められますか？

リフレッシュトークンが失効した場合、アプリケーションが削除された場合、またはメンバーが無効化された場合、トークンエンドポイントは invalid_grant を返します。クライアントはメンバーに再認可を依頼する必要があります。client secret の再生成では、発行済みトークンは無効になりません。