Skip to Content
User Guide🎁 特別機能カスタムMCPサーバーOAuth2内部処理フロー

OAuth2内部処理フロー

Custom MCPサーバーにOAuth2認証を連携する際、AIP内部で行われる処理過程を詳細に説明します。OAuth2認証・DCRガイドのユーザー視点の説明を補完する技術詳細ドキュメントです。

このドキュメントの活用

OAuth2認証・DCRガイドは「どのように連携するか」に焦点を当てています。ほとんどの場合それだけで十分ですが、以下の状況ではAIP内部の処理フローを理解する必要があります。

連携失敗の診断 — OAuthポップアップが表示されない、または認証が失敗する場合、内部フローを理解することで、Discovery、Token Exchange、トークン更新のどの段階で問題が発生したかを正確に診断できます。例えば、OAuthポップアップがまったく表示されない場合はDiscovery段階の失敗であり、ポップアップは表示されたがログイン後にエラーが発生した場合はToken Exchangeの問題です。

セキュリティレビューおよび監査対応 — 企業のセキュリティチームがOAuth実装の安全性をレビューする際に必要な情報を提供します。「Authorization Codeが傍受されたらどうなるか？」という質問に対して、AIPがPKCE（Proof Key for Code Exchange）を自動適用してコード傍受攻撃を防止していることを本ドキュメントを根拠に説明できます。StateトークンによるCSRF防止、Client Secretのサーバー側管理、TLSによる通信暗号化など、セキュリティメカニズムの詳細を確認できます。

MCPサーバー開発者の実装判断 — MCPサーバー開発者がAuthorization Serverを実装する際、AIPが実際にどのようなリクエストを送信し、どのような応答を期待するかを知る必要があります。例えば、ASMにcode_challenge_methods_supportedを含めるかどうか、Token Endpointでcode_verifierをどのように検証するか、DCR登録リクエストの形式と必須フィールドは何かなどの判断に本ドキュメントが参考になります。PKCEをサポートしない場合、AIPはPKCEなしで処理を進めますが、サポートするとセキュリティが強化されるため実装を推奨します。

トークンライフサイクルの理解 — Access Tokenの期限切れ、Refresh Tokenの更新、Client Secretの変更など、運用中に発生するトークン関連の課題を理解し対応するために必要な情報を提供します。AIPがRefresh Tokenを使用して自動的にAccess Tokenを更新するフロー、Refresh Token自体が期限切れになった場合の再認証手続き、Client Secretが変更された場合の再設定方法などを扱います。

全体フロー概要

MCP Server URLを入力すると、AIPは以下の順序で処理を行います：

  1. メタデータ照会 — OAuth Discoveryを通じて認証方式を判定します。
  2. クライアント登録または手動入力 — DCR対応状況に応じて自動登録するか、ユーザーにClient ID/Secretを要求します。
  3. Authorization URL生成 — PKCEを含むAuthorization Code Flowを開始します。
  4. OAuthポップアップ — ユーザーがサービスにログインします。
  5. コールバック処理およびトークン交換 — Authorization CodeをAccess Tokenに交換します。
  6. トークン保存 — ユーザーごとにトークンを保存し、連携を完了します。

ステップ1：OAuth Discoveryおよび認証方式判定

メタデータ照会順序

MCP Server URLが入力されると、AIPバックエンドが以下の順序でメタデータを照会します：

Protected Resource Metadata（PRM）照会

MCPサーバーにPOSTリクエストを送信して認証の必要性を確認します。

  • 401応答 + WWW-Authenticateヘッダー：ヘッダーからresource_metadata URLを抽出してPRMを取得します。
  • 401以外の応答：/.well-known/oauth-protected-resourceエンドポイントに直接照会します。

PRMからauthorization_serversフィールドを抽出してAuthorization Serverの位置を確認します。

Authorization Server Metadata（ASM）照会

PRMから取得したAuthorization Server URLを基にASMを照会します。以下のパスを優先順位順に試行します：

  1. RFC 8414：/.well-known/oauth-authorization-server/{path}
  2. OIDC（path insertion）：/.well-known/openid-configuration/{path}
  3. OIDC（path appending）：/{path}/.well-known/openid-configuration

ASM応答にはauthorization_endpoint、token_endpoint、scopes_supported、registration_endpoint（任意）などが含まれます。

認証方式判定

ASM照会結果に基づいて認証方式を決定します：

条件判定結果
ASM照会失敗NoAuth — OAuthフローを開始しない
ASMにregistration_endpointありOAuthWithDCR — 自動クライアント登録
ASMにregistration_endpointなしOAuth — 手動Client ID/Secret入力

ASMのissuerフィールドはRFC 8414に従って検証されます。一部のサービス（例：Slack）でサブドメインが異なる場合、互換性のためfallback処理が適用されます。

Discovery実行タイミング

OAuth Discovery（PRM → ASM照会）は2回実行されます：

  1. MCP Server URL入力時 — 認証方式（NoAuth / OAuthWithDCR / OAuth）を判定するために実行されます。この結果に基づいて、ユーザーに表示するUI（自動進行 / Client ID・Secret入力ダイアログ / OAuthなしで続行）が決定されます。
  2. Client ID/Secret送信時（またはDCR登録時） — Authorization URLを生成するために再度実行されます。この時点でASMからauthorization_endpoint、token_endpoint、scopes_supportedなどの最新値を取得し、認可リクエストに使用します。

2回目の実行は、最初の照会と実際の認可リクエストの間に時間差が発生する可能性があるため、最新のメタデータを使用するためのものです。

ステップ2：クライアント登録または手動入力

OAuthWithDCRの場合（自動登録）

AIPがASMのregistration_endpointにRFC 7591形式でクライアント登録リクエストを送信します：

POST {registration_endpoint}
Content-Type: application/json

{
  "client_name": "Custom MCP Client of AI Platform",
  "redirect_uris": ["https://{aip-domain}/integration/oauth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "scope": "read write",
  "token_endpoint_auth_method": "client_secret_basic"
}

成功時、client_idとclient_secretを自動で取得し、ステップ3に進みます。

DCR登録が失敗した場合、AIPは自動的に手動入力方式にfallbackします。ユーザーにClient ID/Secret入力ダイアログが表示されます。

OAuthの場合（手動入力）

ユーザーにClient ID/Secret入力ダイアログを表示します。ダイアログには以下の情報が含まれます：

  • MCP Server URL — 連携先サーバーアドレス
  • OAuth Callback URL — ユーザーが外部サービスのOAuth Appに登録する必要があるRedirect URI（コピーボタン付き）
  • 必要Scope一覧 — ASMのscopes_supportedから取得した権限一覧
  • Client ID / Client Secret入力フィールド

ユーザーは外部サービスでOAuth Appを作成し、Callback URLを登録した後、発行されたClient IDとSecretを入力します。

認証失敗時、エラーメッセージとともにダイアログが再表示され、以前の入力値が自動で入力されるため、再試行が容易です。

ステップ3：Authorization URL生成

Client ID/Secretが確保されると（DCR自動発行または手動入力）、AIPバックエンドがAuthorization URLを生成します。

PKCE（Proof Key for Code Exchange）

ASMのcode_challenge_methods_supportedにS256が含まれている場合、AIPは自動的にPKCEを適用します：

  1. Code Verifier生成 — 暗号学的に安全なランダム文字列
  2. Code Challenge生成 — BASE64URL(SHA256(code_verifier))
  3. Code Verifierはサーバー側にのみ保存し、Code ChallengeのみをAuthorization URLに含めます

MCPサーバー開発者は、Authorization Server Metadataに code_challenge_methods_supported: ["S256"] を含めることを強く推奨します。このフィールドがないとAIPはPKCEなしで処理を進めますが、Authorization Code傍受攻撃を防ぐためにPKCEの実装を強く推奨します。

Stateトークン

CSRF攻撃防止のため、1回限りのStateトークンを生成します。Stateトークンは暗号学的に安全なランダム値であり、認証処理に必要なセッション情報はAIPサーバー側でのみ管理されます。トークンは約10分間有効で、コールバックで1回消費されると即座に削除されます。

Authorization URLパラメータ

最終生成されるAuthorization URLには以下のパラメータが含まれます：

パラメータ説明
client_idDCR発行または手動入力されたClient ID
redirect_uriAIPのOAuthコールバックURL
response_typecode（Authorization Code Flow）
state1回限りのCSRF防止トークン
code_challengePKCE Challenge（対応時）
code_challenge_methodS256（対応時）
scopeASMのscopes_supported
resourceRFC 8707 Resource Indicator（対応時）

ステップ4：OAuthポップアップ

生成されたAuthorization URLでブラウザポップアップが開き、ユーザーは外部サービスにログインします。ログイン成功後、サービスはAIPのコールバックURLにcodeとstateを含めてリダイレクトします。

ステップ5：コールバック処理およびトークン交換

コールバック受信

GET /integration/oauth/callback?state={state}&code={code}

AIPは以下を実行します：

State検証

受信したstate値で保存されたセッション情報を照会します。Stateが無効または期限切れの場合、認証が失敗します。

Token Exchange

保存された情報（Client ID、Client Secret、Code Verifier）を使用してToken Endpointにコード交換をリクエストします：

POST {token_endpoint}
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={authorization_code}
&client_id={client_id}
&client_secret={client_secret}
&redirect_uri={callback_url}
&code_verifier={code_verifier}

トークン受信

Token Endpointから以下を応答として受け取ります：

フィールド説明
access_tokenAPI呼び出しに使用するアクセストークン
refresh_tokenトークン更新に使用するリフレッシュトークン（任意）
expires_inアクセストークンの有効期限（秒）

ステップ6：トークン保存および連携完了

Auth Ticket

トークン交換が成功すると、AIPはAuth Ticketを生成します。Auth Ticketは1回限りの一時トークンで、フロントエンドに渡されて連携インストールを完了するために使用されます。

Auth Ticketには以下が含まれます：

項目用途
Access TokenMCPサーバーAPI呼び出し
Refresh Tokenトークン期限切れ時の更新
Client ID / Client Secretトークン更新リクエスト時の認証
Token Endpointトークン更新リクエスト先URL

ユーザー別トークン管理

トークンはユーザーごとに独立して保存されます。同一MCPサーバーに対して複数のユーザーがそれぞれ認証すると、各ユーザーは自分だけのトークンを持ちます。

トークン更新

Access Tokenが期限切れになると、AIPは保存されたRefresh Tokenを使用して自動的に更新します：

POST {token_endpoint}
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={refresh_token}
&client_id={client_id}
&client_secret={client_secret}

更新が成功すると、新しいAccess Token（場合によっては新しいRefresh Tokenも）が保存されます。Refresh Tokenが期限切れまたは失効した場合、ユーザーは再度OAuth認証を行う必要があります。

セキュリティ考慮事項

PKCE（Proof Key for Code Exchange）

AIPはAuthorization ServerがPKCEをサポートする場合、自動的に適用します。PKCEはAuthorization Code傍受攻撃を防止し、MCP仕様で推奨されるセキュリティメカニズムです。

  • Code Verifierはサーバー側にのみ保存され、クライアントに公開されません。
  • Code ChallengeはSHA-256ハッシュであるため、元のVerifierを逆算することはできません。

Stateトークン

  • 暗号学的に安全なランダム値として生成されます。
  • 約10分間有効で、1回使用後に即座に削除されます。
  • CSRF（Cross-Site Request Forgery）攻撃を防止します。

Client Secretの保管

  • 手動入力されたClient SecretはAuth Ticketに含まれ、サーバー側でのみ管理されます。
  • トークン更新時に必要なため、Access Tokenと合わせて保存されます。
  • すべての通信はTLS（HTTPS）上で行われます。

Redirect URI検証

外部サービスのOAuth AppにAIPのコールバックURLが正確に登録されている必要があります。Redirect URIが一致しない場合、Authorization Serverがリクエストを拒否します。

トラブルシューティング

DCR登録失敗後の手動入力切り替え

DCR登録が失敗すると、AIPは自動的に手動入力ダイアログを表示します。主な失敗原因：

  • Authorization ServerがDCRリクエスト形式をサポートしていない場合
  • registration_endpointがASMに存在するが、実際には動作しない場合
  • ネットワークエラーまたはタイムアウト

Token Exchange失敗

コールバックは受信されたがトークン交換が失敗する場合：

  • Client ID/Secretが正確か確認します。
  • OAuth AppのRedirect URIがAIPコールバックURLと正確に一致するか確認します。
  • Authorization ServerのToken Endpointが正常に動作しているか確認します。

トークン更新失敗

  • Refresh Tokenが期限切れまたは失効した場合、ユーザーに再認証を要求します。
  • Client Secretが変更された場合、MCP連携を削除して新しいClient ID/Secretで再設定します。

State期限切れ

OAuthポップアップでのログインに10分以上かかると、Stateトークンが期限切れになります。この場合、連携設定をやり直す必要があります。

Last updated on
OAuth2認証・DCRガイドローカルMCPプロキシ