MCP Oauth2
1. はじめに
mcp-oauth2 は Kong plugin/policy であり、MCP HTTP endpoints を OAuth2/OIDC を使用して保護します（一般的には Keycloak と共に使用されます）。
提供される機能:
- Client discovery を通じて /.well-known/oauth-protected-resource (RFC 9728) により、MCP クライアントは認証サーバーとサポートされているスコープを学ぶことができます。
- JWT access-token validation: iss (発行者)、aud (受信者)、および JWKS を使用して署名を確認します。
- （オプション）authorization by scope/role （例: mcp_scopes のようなクレームから）を、スコープを許可された MCP JSON-RPC メソッドにマッピングすることによって提供します。
2. APIM コンソールの設定
ステップ 1: バックエンドを MCP サーバーに設定した新しい API を作成します。
MCP サーバー: http://wikipedia-mcp.default.svc.cluster.local:8080/mcp
VS Code からこの API を通じて MCP サーバーにアクセスする必要があるため、VS Code は追加のパスセグメントを持つ URL をサポートしていないので、Base Path を “/” （パスなし）に設定します。
ステップ 2: mcp-oauth2 ポリシーを API に適用します。
ステップ 3: mcp-oauth2 ポリシーボタンをクリックして、以下の設定詳細を表示します。
Section 1: PROTECTED RESOURCE METADATA (RFC 9728)
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| Protected Resource Metadata Path | string | Yes | /.well-known/oauth-protected-resource | • プラグインがRFC 9728の保護されたリソースメタデータ文書を提供するURLパスです。 • MCPクライアントはこれを取得して、認証サーバーとサポートされているスコープを発見します。 • ほとんど変更する必要はありません。 |
- 信頼された認証サーバーの配列です。このMCPエンドポイントのトークンを発行するKeycloakレルム（または他のOAuth2プロバイダー）ごとに1つのエントリを追加します。
- +をクリックして、さらにエントリを追加します。
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| Url | string | Yes | • public URL of the authorization server（クライアントが認証/トークンを取得する場所）です。
• jwks_uriが相対パスの場合、base URL for building the JWKS URLでもあります。
Example: https://keycloak-demo.apimags.skcloud.io/realms/master | | Issuer | string | Yes | • JWTのiss（発行者）クレームに対して一致します。
• トークンの発行者が一致しない場合、拒否されます。
• exact string matchである必要があります。 • プロトコル、ホスト、ポート、パスを含む（末尾のスラッシュは不要です）。
• Find it at:{realm-url}/.well-known/openid-configuration→ 発行者フィールド。 | | Audience | string | Yes | • JWTのaud（受信者）クレームに対して一致します。
• 他のサービス向けのトークンが受け入れられないようにします。
• Must exactly match KeycloakのAudience Mapperで設定された値です。 | | JWKS URI | 文字列 | はい | • プラグインがJWT署名を検証するために認証サーバーの公開署名鍵（JWKS）を取得するエンドポイント。
• 次のようになります: Relative path （Urlに追加される）: /.well-known/jwks.json Absolute URL （そのまま使用される）: https://keycloak-demo.apimags.skcloud.io /realms/master/protocol/openid-connect/certs Kongがクライアントと同じホスト名を介して認証サーバーにアクセスできない場合は、絶対URLを使用してください（例: Docker/k8sネットワーキング）。 Default: /.well-known/jwks.json |
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| Scopes Supported | 文字列の配列 | はい | 空 | クライアントに要求するスコープを伝えるために、保護されたリソースメタデータ文書に記載されています。これは informational only • クライアントの発見をガイドしますが、何も強制しません。 各スコープを入力し、Enter を押して追加します。 Example: mcp:tools |
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| Authorization Header Name | 文字列 | はい | 認証 | • Authorization Header Name = トークン検証のためにサーバー/プラグインがアクセス・トークンを見つけるために読むHTTPヘッダー名。 • 通常は Authorization のままにします。 • クライアントは次のようにトークンを送信します: Authorization: Bearer <access_token> • APIが異なるヘッダー にトークンを期待する場合のみ変更します（例: X-Authorization）。 |
Section 4: UPSTREAM TOKEN FORWARDING
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| Forward Authorization Header | boolean | いいえ | false | • false - MCPサーバーに転送する前にAuthorizationヘッダーを削除します（より安全なデフォルト）。 • true - Bearer <token> ヘッダーを上流のMCPサーバーに転送します。 • MCPサーバーがトークンを読み取る必要がある場合は有効にします（例：ユーザーのアイデンティティやクレームを抽出するため）。 |
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| Enable ACL | boolean | いいえ | false | false - 有効なトークンはすべてのMCPメソッドへのアクセスを許可します（トークンの検証は引き続き行われます）。 true - トークンを検証した後、プラグインはトークンのスコープ/ロールをScope Method Mappingと照らし合わせて、特定のJSON-RPCメソッドが許可されているかどうかを確認します。 |
| ACL Claim | string | いいえ | scope | • ユーザーの権限を含むJWTクレームの名前。プラグインはこのクレームを読み取り、その値をACLチェックに使用します。 • 一般的な値： → mcp_scopes - Keycloakプロトコルマッパーからのカスタムクレーム ⚠️ Keycloakプロトコルマッパーでトークンクレーム名をexactly matchする必要があります。 |
各スコープ/ロールを、そのスコープが呼び出すことを許可されているMCP JSON-RPCメソッドのリストにマッピングします。Enable ACLがtrueのときのみ有効です。
| Field | Type | Required | Description |
|---|---|---|---|
| Scope | string | Yes (per entry) | スコープ/ロール名。JWTクレームに指定された値と一致する必要があります ACL Claim. Example: mcp:tools |
| Methods | array of strings | Yes (per entry) | このスコープが呼び出すことを許可されているMCP JSON-RPCメソッド名。各メソッド名を入力し、Enterを押して追加します。 Example: tools/list, tools/call |
⚠️ When ACL is enabled but Scope Method Mapping is empty: すべてのリクエストは拒否されます。少なくとも1つのマッピングを構成する必要があります。
💡 Permissions are additive: ユーザーは、メソッドを許可するために1つのスコープのみが必要です。トークン内のいずれかのスコープがメソッドを許可している場合、アクセスが許可されます。
Section 7: TIMEOUTS & CACHING| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| Token Cache TTL (s) | number | No | 300 | 検証されたトークンがKongの共有メモリにキャッシュされる時間（秒単位）。この期間中、同じトークンでの繰り返しリクエストはJWTデコードと署名検証をスキップします。 キャッシュされていても、プラグインはすべてのリクエストでJWT expクレームを再チェックし、期限切れのトークンを無効にします。 |
| HTTP Timeout (ms) | number | No | 10000 | 認証サーバーからJWKS（公開署名キー）を取得するためのHTTPリクエストのタイムアウト（ミリ秒単位）。この時間内に認証サーバーが応答しない場合、トークンの検証は失敗します。 • 認証サーバーが遅いネットワーク上にある場合やコールドスタート中の場合は増加させてください。 • 認証サーバーに到達できない場合は、より早く失敗するために減少させてください。 |
3. Keycloak Setup
3.1. Keycloak OAuth2 Foundation
これらの手順は、MCPクライアントが認証サーバーを発見し、正しいオーディエンスでトークンを取得できるようにKeycloakを構成します。
3.1.1 Create the Client Scope
What this does: クライアントがリクエストできる名前付きスコープを作成します。クライアントがスコープを要求すると、 Keycloak はそれをトークンに含めます - このスコープに添付されたマッパーも発火します。
Step 1: Navigate to Keycloak Admin → Client scopes → Create client scope
| Field | Value | Why |
|---|---|---|
| Name | mcp:tools | あなたのMCPクライアントがリクエストするスコープ名 |
| Protocol | OpenID Connect | 標準のOAuth2/OIDCプロトコル |
| Display on consent screen | ON | ログイン中にクライアントがリクエストしている内容を示します |
| Consent screen text | Access MCP tools | ユーザー向けの人間が読める説明 |
| Include in token scope | ON | スコープ値がJWTスコープクレームに表示されることを保証します |
3.1.2 Add the Audience Mapper
What this does: アクセス・トークンに aud (オーディエンス) クレームを追加します。このプラグインは、トークンのオーディエンスが設定された値と一致することを検証します - これにより、other サービス用に発行されたトークンがあなたのMCPエンドポイントで受け入れられないようにします。
Step 1: Navigate to The mcp:tools scope you just created → Mappers tab → Configure a new mapper → Select Audience
| Field | Value | Why |
|---|---|---|
| Name | audience-config | このマッパーの説明的な名前 |
| Included Custom Audience | audience-name | Kongプラグイン設定のaudienceフィールドと一致する必要があります |
| Add to access token | ON | プラグインはアクセストークンを読み取ります。IDトークンではありません。 |
| Add to ID token | OFF | IDトークンはクライアントアプリ用であり、リソースサーバー用ではありません。 |
 |
3.1.3. 新しいクライアントを作成
What this does: MCPクライアントがKeycloakに接続するためのクライアントを作成します。
Step 1: Navigate to Clients → Create client
| Field | Value | Description |
|---|---|---|
| Client ID | Mcp-client | クライアントID |
3.2. Keycloak: グループベースのACL設定
このセクションでは、fine-grained access controlを設定して、異なるユーザーに異なるMCP権限を付与します。アーキテクチャは次のとおりです。
グループ → レルムロール → プロトコルマッパー → "mcp_scopes" JWTクレーム → ACL
3.2.1. レルムロールを作成
What these are: 名前付き権限層。各ロールは、ユーザーが呼び出すことを許可されたMCPメソッドのセットを表します。ロール名はJWTのmcp_scopesクレームに表示されます。
Step 1: Navigate to: Realm roles → Create role (repeat for each)
| Role Name | Purpose | Example MCP Methods |
|---|---|---|
| mcp:tools | ツールへのアクセス | tools/list |
| mcp:resources | リソースへのアクセス | resources/read |
 |
3.2.2. グループの作成
What these are: ユーザーのための組織的コンテナです。ユーザーごとに役割を割り当てるのではなく、グループに役割を割り当て、その後ユーザーをグループに追加します。
Step 1: Navigate to: Groups → Create group
| Group Name | Description |
|---|---|
| mcp-member | 基本メンバーアクセス |
| mcp-admin | すべてのMCPツール、リソースへのフルアクセス |
 |
3.2.3. グループに役割を割り当てる
Step 1: Navigate to Groups → Click a group → Role mapping tab → Assign role| Group | Roles to Assign |
|---|---|
| Mcp-admin | mcp:tools, mcp:resources |
| Mcp-member | mcp:tools |
 |
クリックして Assign
3.2.4. プロトコルマッパーの作成 (mcp_scopes クレーム)
What this does: Keycloakにユーザーの領域役割（mcp:プレフィックスでフィルタリングされた）を、アクセス トークン内のmcp_scopesというカスタムクレームとして含めるように指示します。これは、KongプラグインがACLの決定を行うために読み取るクレームです。 Step 4: Navigate to Client scopes → mcp:tools → Mappers tab → Add mapper → By configuration → Select User Realm Role
| Field | Value | Why |
|---|---|---|
| Name | mcp-scopes-mapper | 説明的な名前 |
| Mapper Type | ユーザー領域ロール | ユーザーの領域ロールをトークンクレームにマッピングします |
| Token Claim Name | mcp_scopes | Kongプラグイン設定のacl_claimと一致する必要があります |
| Multivalued | ON | ユーザーは複数のロールを持つことができます |
| Add to access token | ON | プラグインはアクセストークンを読み取ります |
| Add to ID token | OFF | リソースサーバーの検証には必要ありません |
| Add to userinfo | OFF | 必要ありません |
Critical: Token Claim Name (mcp_scopes) は、Kongプラグイン設定のacl_claimフィールドと一致する必要があります。不一致があると、プラグインはトークン内の権限を見つけることができません。
3.2.5. ユーザーをグループに追加
Step 1: Navigate to Users → Click on a user → Groups tab → Join group → Select the appropriate group
| User | Group | Resulting JWT mcp_scopes |
|---|---|---|
| canhng1 | Mcp-member | Mcp:tools, Mcp:resources |
| admin | mcp-admin | Mcp:resources |
 |
4. Visual Studio Codeを使用したテスト
4.1. Kongプロキシをローカルに転送
4.2. 新しいMCPサーバーを作成する
Vs Codeを開き、Ctrl + Shift + Pを押して、MCP: Add serverを選択します…。HTTPを選択し、http://localhost:8100.を入力します。サーバーにVisual Studio Code内で使用するためのユニークな名前を付けます。mcp.jsonには、次のようなエントリが表示されるはずです：
4.3. サーバーを起動し、Keyloak認証を使用してモックMCPサーバーに接続する
ログイン成功、22のツールでモックMCPサーバーに接続されました。