mcp: JWT scope based authorization by zhaohuabing · Pull Request #1482 · envoyproxy/ai-gateway

zhaohuabing · 2025-11-04T07:14:52Z

Description

This PR introduces MCP spec compatible scope based authorization for MCPRoutes.

According to the 2025-11-25 version of the MCP spec, the MCP Gateway should enforce scope-based authorization on behalf of the backend MCP server, and include the required scopes in the WWW-Authenticate header of the 403 response if authoriation fails.

https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#runtime-insufficient-scope-errors

When a client makes a request with an access token with insufficient scope during runtime operations, the server SHOULD respond with:
HTTP 403 Forbidden status code
WWW-Authenticate header with the Bearer scheme and additional parameters:
error="insufficient_scope" - indicating the specific type of authorization failure
scope="required_scope1 required_scope2" - specifying the minimum scopes needed for the operation
resource_metadata - the URI of the Protected Resource Metadata document (for consistency with 401 responses)
error_description (optional) - human-readable description of the error

Example:

spec:
  ...
  securityPolicy:
    oauth:
      ...
    authorization:
      rules:
        - source:
            jwt:
              scopes:
                - echo
          target:
            tools:
              - backend: mcp-backend-authorization
                toolName: echo
                when: args.text.matches("^Hello, .*!$")
        - source:
            jwt:
              scopes:
                - sum
          target:
            tools:
              - backend: mcp-backend-authorization
                toolName: sum

Reference: https://modelcontextprotocol.io/specification/draft/basic/authorization#scope-challenge-handling

Implements #1459

codecov-commenter · 2025-11-04T07:17:33Z

Codecov Report

❌ Patch coverage is 63.42857% with 64 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.17%. Comparing base (2c3b46f) to head (4b8bc39).
⚠️ Report is 129 commits behind head on main.

Files with missing lines	Patch %	Lines
internal/controller/gateway.go	0.00%	30 Missing and 1 partial ⚠️
internal/mcpproxy/authorization.go	81.74%	16 Missing and 7 partials ⚠️
internal/mcpproxy/handlers.go	20.00%	7 Missing and 1 partial ⚠️
internal/mcpproxy/config.go	50.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1482      +/-   ##
==========================================
- Coverage   83.46%   83.17%   -0.29%     
==========================================
  Files         138      139       +1     
  Lines       12540    12711     +171     
==========================================
+ Hits        10466    10573     +107     
- Misses       1440     1494      +54     
- Partials      634      644      +10

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

api/v1alpha1/mcp_route.go

internal/mcpproxy/authorization.go

internal/mcpproxy/handlers.go

zhaohuabing · 2025-12-03T03:27:57Z

api/v1alpha1/mcp_route.go

+	// +kubebuilder:validation:Optional
+	// +kubebuilder:validation:MaxLength=4096
+	// +optional
+	Arguments *string `json:"arguments,omitempty"`


After discussing this with @nacx offline, we chose CEL for argument evaluation.

CEL is easier to write and understand than regex evaluation when the arguments are complex object types.

For example:

To check against this argument:

{ "key-level1": { "key-level2": { "key-level3": "value" } } }

The regex match:

/"key-level1"\s*:\s*\{\s*"key-level2"\s*:\s*\{\s*"key-level3"\s*:\s*"value"\s*\}\s*\}/gm

The CEL match:

args["key-level1"]["key-level2"]["key-level3"] == "value"

WDYT about renaming this to condition? If we do this, we could also easily support meta in addition to args to have policies based on the contents of the metadata.

Should meta be inside the ToolCall, or MCPAuthorizationTarget?

Oh meta is part of the CallToolParams - then condition is a good.

Thinking about it again, condition feels a bit vague and also used in the status field, some alternatives:

When

Predicate

Matcher

When reads naturally in the context of authorization rules:

tools: - backend: backend1 tool: listFiles when: args.folder == "restricted"

I like the when better than the other two options. It is also used for additional conditions in Istio AuthorizationPolicies, so it's not a completely foreign name.

Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com>

nacx · 2025-12-17T10:12:14Z

internal/mcpproxy/authorization.go

+	} else {
+		claims := jwt.MapClaims{}
+		// JWT verification is performed by Envoy before reaching here. So we only need to parse the token without verification.
+		if _, _, err := jwt.NewParser().ParseUnverified(token, claims); err != nil {


Explained in the comment why verification is not needed here

Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com>

zhaohuabing · 2025-12-04T08:15:58Z

WDYT about renaming this to condition? If we do this, we could also easily support meta in addition to args to have policies based on the contents of the metadata.

https://github.com/envoyproxy/ai-gateway/pull/1482/files#r2587966887

Thinking about it again, condition feels a bit vague and also used in the status field, some alternatives:

When
Predicate
Matcher

When reads naturally in the context of authorization rules:

tools:
  - backend: backend1
    tool: listFiles
    when: args.folder == "restricted"

Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com>

nacx

LGTM! Just one final comment about validations and API semantics, but this looks good!

api/v1alpha1/mcp_route.go

Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com>

Signed-off-by: Huabing(Robin) Zhao <zhaohuabing@gmail.com>

zhaohuabing · 2025-12-17T02:14:26Z

The CI failure is not related to this PR:

We'll need to create a PAT to access the Github MCP server.

time=2025-12-16T23:48:41.239Z level=ERROR msg="failed to create MCP session" component=mcp-proxy backend=github error="MCP initialize request failed with status code 400 and body=bad request: GitHub App Server-To-Server Tokens are not supported for this endpoint\n"

nacx · 2025-12-17T09:34:17Z

Yeah, looks like there are changes on the GH MCP: github/github-mcp-server#1610

nacx · 2025-12-17T09:59:55Z

/retest

@zhaohuabing

…oxy#1608) **Description** Add the configured scopes to the `WWW-Authenticate` headers. At initialization time, which is when the first authentication will occur, we don't have enough information to provide a fine-grained list of scopes, so the best we can do is to default to the ones defined in the protected resource metadata. **Related Issues/PRs (if applicable)** Fixes envoyproxy#1578 The addition of the header on 403 requests is implemented in envoyproxy#1482, but this issue can be closed as soon as this PR is merged, because we'll be compatible with the latest spec. **Special notes for reviewers (if applicable)** cc @zhaohuabing can you take a look? Signed-off-by: Ignasi Barrera <nacx@apache.org> Signed-off-by: Erica Hughberg <erica.sundberg.90@gmail.com>

**Description** This PR introduces MCP spec compatible scope based authorization for MCPRoutes. According to the 2025-11-25 version of the MCP spec, the MCP Gateway should enforce scope-based authorization on behalf of the backend MCP server, and include the required scopes in the `WWW-Authenticate` header of the 403 response if authoriation fails. https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#runtime-insufficient-scope-errors > When a client makes a request with an access token with insufficient scope during runtime operations, the server SHOULD respond with: HTTP 403 Forbidden status code WWW-Authenticate header with the Bearer scheme and additional parameters: error="insufficient_scope" - indicating the specific type of authorization failure scope="required_scope1 required_scope2" - specifying the minimum scopes needed for the operation resource_metadata - the URI of the Protected Resource Metadata document (for consistency with 401 responses) error_description (optional) - human-readable description of the error Example: ```yaml spec: ... securityPolicy: oauth: ... authorization: rules: - source: jwt: scopes: - echo target: tools: - backend: mcp-backend-authorization toolName: echo when: args.text.matches("^Hello, .*!$") - source: jwt: scopes: - sum target: tools: - backend: mcp-backend-authorization toolName: sum ``` Reference: https://modelcontextprotocol.io/specification/draft/basic/authorization#scope-challenge-handling Implements envoyproxy#1459 --------- Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com> Signed-off-by: Huabing(Robin) Zhao <zhaohuabing@gmail.com> Co-authored-by: Ignasi Barrera <ignasi@tetrate.io> Signed-off-by: Erica Hughberg <erica.sundberg.90@gmail.com>

zhaohuabing requested a review from a team as a code owner November 4, 2025 07:14

zhaohuabing marked this pull request as draft November 4, 2025 07:14

dosubot bot added the size:L This PR changes 100-499 lines, ignoring generated files. label Nov 4, 2025

zhaohuabing force-pushed the mcp-authorization branch 2 times, most recently from d1ea251 to 877d598 Compare November 4, 2025 07:45

zhaohuabing commented Nov 4, 2025

View reviewed changes

api/v1alpha1/mcp_route.go Outdated Show resolved Hide resolved

zhaohuabing commented Nov 4, 2025

View reviewed changes

api/v1alpha1/mcp_route.go Show resolved Hide resolved

zhaohuabing force-pushed the mcp-authorization branch 2 times, most recently from 4d2e8d5 to 0ccf737 Compare November 4, 2025 08:05

nacx self-assigned this Nov 4, 2025

zhaohuabing force-pushed the mcp-authorization branch 4 times, most recently from 29db138 to 2dd862c Compare November 28, 2025 09:32

github-advanced-security bot found potential problems Nov 28, 2025

View reviewed changes

internal/mcpproxy/authorization.go Fixed Show fixed Hide fixed

zhaohuabing force-pushed the mcp-authorization branch 3 times, most recently from 2167726 to a95087c Compare December 2, 2025 02:14

github-advanced-security bot found potential problems Dec 2, 2025

View reviewed changes

internal/mcpproxy/authorization.go Fixed Show fixed Hide fixed

zhaohuabing marked this pull request as ready for review December 2, 2025 03:21

dosubot bot added size:XXL This PR changes 1000+ lines, ignoring generated files. and removed size:L This PR changes 100-499 lines, ignoring generated files. labels Dec 2, 2025

zhaohuabing commented Dec 2, 2025

View reviewed changes

internal/mcpproxy/handlers.go Outdated Show resolved Hide resolved

zhaohuabing force-pushed the mcp-authorization branch 5 times, most recently from b77c937 to f8a07cc Compare December 3, 2025 03:19

zhaohuabing commented Dec 3, 2025

View reviewed changes

support defaultAction and action in rules

b8e32a6

Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com>

github-advanced-security bot found potential problems Dec 4, 2025

View reviewed changes

rename arguments to condition

dab18f8

Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com>

rename ToolName to Tool

9271f0b

Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com>

zhaohuabing force-pushed the mcp-authorization branch from b908be0 to 9271f0b Compare December 4, 2025 09:52

zhaohuabing requested a review from nacx December 4, 2025 10:01

zhaohuabing added 2 commits December 9, 2025 16:15

Merge remote-tracking branch 'origin/main' into mcp-authorization

6da4a6d

rename condition to when

48cb092

Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com>

nacx reviewed Dec 15, 2025

View reviewed changes

api/v1alpha1/mcp_route.go Outdated Show resolved Hide resolved

update validation

fc15467

Signed-off-by: Huabing Zhao <zhaohuabing@gmail.com>

zhaohuabing force-pushed the mcp-authorization branch from 4d456ac to fc15467 Compare December 16, 2025 01:05

Merge branch 'main' into mcp-authorization

836b4b0

zhaohuabing marked this pull request as draft December 16, 2025 01:56

add more tests

fefa1e6

Signed-off-by: Huabing(Robin) Zhao <zhaohuabing@gmail.com>

zhaohuabing force-pushed the mcp-authorization branch from 395cf5a to fefa1e6 Compare December 16, 2025 13:29

zhaohuabing marked this pull request as ready for review December 16, 2025 13:37

add test for CEL

ce604c5

Signed-off-by: Huabing(Robin) Zhao <zhaohuabing@gmail.com>

zhaohuabing requested a review from nacx December 16, 2025 14:04

Merge branch 'main' into mcp-authorization

9e1dfb0

Merge branch 'main' into mcp-authorization

4b8bc39

nacx approved these changes Dec 17, 2025

View reviewed changes

nacx merged commit eb7f7b7 into envoyproxy:main Dec 17, 2025
47 of 49 checks passed

zhaohuabing deleted the mcp-authorization branch December 17, 2025 10:19

nacx mentioned this pull request Dec 29, 2025

mcp: fine-grained access control on tools #1459

Closed

Conversation

zhaohuabing commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zhaohuabing Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

nacx Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

zhaohuabing Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zhaohuabing Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

zhaohuabing Dec 4, 2025

Choose a reason for hiding this comment

Uh oh!

nacx Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

Check failure

Uh oh!

nacx Dec 17, 2025

Choose a reason for hiding this comment

Uh oh!

zhaohuabing commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nacx left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zhaohuabing commented Dec 17, 2025

Uh oh!

nacx commented Dec 17, 2025

Uh oh!

nacx commented Dec 17, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zhaohuabing commented Nov 4, 2025 •

edited

Loading

codecov-commenter commented Nov 4, 2025 •

edited

Loading

zhaohuabing Dec 4, 2025 •

edited

Loading

zhaohuabing commented Dec 4, 2025 •

edited

Loading