feat(auth): Add 403 Forbidden `insufficient_scope` support per MCP Auth Spec 2025-11-25 and RFC 6750 (Section 3.1) by gocamille · Pull Request #537 · apollographql/apollo-mcp-server

gocamille · 2026-01-06T16:37:35Z

Summary

This adds HTTP 403 Forbidden responses with error="insufficient_scope" per MCP Auth Spec 2025-11-25 Section 10: Error Handling and RFC 6750 Section 3.1.

Changes

www_authenticate.rs: Added BearerError::InsufficientScope enum and error field to WWW-Authenticate header
valid_token.rs: Extract scope/scp claims from JWTs (handles both standard OAuth and Azure AD)
auth.rs: Scope validation with fail-closed behaviour—valid tokens lacking required scopes get 403
headers.rs: Updated tests for new ValidToken struct

Behavior

401 Unauthorized: Missing or invalid token
403 Forbidden: Valid token but insufficient scopes (includes error="insufficient_scope" in response)

apollo-librarian · 2026-01-06T16:37:42Z

✅ Docs preview has no changes

The preview was not built because there were no changes.

Build ID: 5beabf5d664ad5d66c2ba16e
Build Logs: View logs

github-actions · 2026-01-07T17:19:33Z

❌ Changeset file missing for PR

All changes should include an associated changeset file.
Please refer to README for more information on generating changesets.

Copilot

Pull request overview

This PR adds HTTP 403 Forbidden responses with error="insufficient_scope" to properly handle valid tokens that lack required OAuth scopes, implementing the MCP Auth Spec 2025-11-25 and RFC 6750 Section 3.1.

Key Changes:

Added scope extraction from JWT tokens (supporting both standard scope and Azure AD scp claims)
Implemented fail-closed scope validation that returns 403 when valid tokens lack required scopes
Enhanced WWW-Authenticate header to include error="insufficient_scope" parameter

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
`crates/apollo-mcp-server/src/headers.rs`	Updated test cases to use new `ValidToken` struct with `token` and `scopes` fields
`crates/apollo-mcp-server/src/auth/www_authenticate.rs`	Added `BearerError` enum with `InsufficientScope` variant and `error` field to Bearer authentication header
`crates/apollo-mcp-server/src/auth/valid_token.rs`	Restructured `ValidToken` to include scopes; added `extract_scopes` function with comprehensive tests for OAuth/Azure AD scope claim handling
`crates/apollo-mcp-server/src/auth.rs`	Implemented scope validation middleware that returns 403 Forbidden when tokens have insufficient scopes

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-07T17:22:24Z

+    // Check if token has required scopes (fail-closed: missing scope claim = insufficient)
+    if !auth_config.scopes.is_empty() {
+        let missing_scopes: Vec<_> = auth_config
+            .scopes
+            .iter()
+            .filter(|required| !valid_token.scopes.iter().any(|s| s == *required))
+            .collect();
+
+        if !missing_scopes.is_empty() {
+            tracing::warn!(
+                required = ?auth_config.scopes,
+                present = ?valid_token.scopes,
+                missing = ?missing_scopes,
+                "Token has insufficient scopes"
+            );
+            tracing::Span::current().record("reason", "insufficient_scope");
+            tracing::Span::current().record("status_code", StatusCode::FORBIDDEN.as_u16());
+            return Err(forbidden_error(&auth_config.scopes));
+        }
+    }


The scope validation logic lacks test coverage. Consider adding test cases for:

A valid token with insufficient scopes should return 403 Forbidden with error="insufficient_scope" in the WWW-Authenticate header

A valid token with all required scopes should succeed

A valid token with no scopes when scopes are required should return 403 Forbidden

A valid token with extra scopes (superset) should succeed

This is critical functionality for the security model and should be thoroughly tested.

This looks like one of those rare times when AI gives a good review. 😃

Implemented test coverage in 3188f91

DaleSeo · 2026-01-07T20:22:22Z

    })?;

+    // Check if token has required scopes (fail-closed: missing scope claim = insufficient)
+    if !auth_config.scopes.is_empty() {


Should we assume that if users set the transport.auth.scopes option to an empty list, they want to skip scope validation completely?

This (and the one below) is a really great question (and super nuanced @DaleSeo !) -- looking at the specs (both MCP and OAuth), this assumption is correct. So when transport.auth.scopes is set to an empty list the following would happen:

Scope validation would be completely skipped

The token would only need to pass signature and audience validation

The scopes_supported field in the protected resource metadata would be empty (which a client could see as "no specific scopes needed")

This seems a reasonable default for those who want simple "authenticated or not" access control, but (and this is related to the comment below too) we may want to consider adding flexibility / complexity in a few ways:

Separating scopes_supported from scopes_required — like you mentioned the MCP spec explicitly says scopes in WWW-Authenticate "may" match scopes_supported, be a subset or superset of it, or an alternative collection, while right now we use one list for enforcement.

Supporting per-tool scope requirements (a big one) — The spec mentions "minimum scopes needed for the operation," so different MCP tools might require different scopes.

Adding "any-of" logic may also be good here, as the current implementation requires all listed scopes while some use cases might only need at least one from a set.

What do you think of the current "all-or-nothing" approach? Should we enhance the flexibility of this to cover any of the above items?

(If we do stay with the current approach I would update the docs to document this clearly, and possibly add a warning when the scopes list is empty)

Thanks for sharing your thoughts, @gocamille! This reminds me that in PR #535, we introduced the allow_any_audience flag instead of treating audiences: [] as skipping validation. I think we should do the same for scopes, and it might be another case where a CORS-like configuration makes sense. Skipping scope validation reduces security, so I would suggest making it an explicit opt-out.

… Spec 2025-11-25

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-09T15:24:20Z

+
+**Changes:**
+- `www_authenticate.rs`: Added `BearerError::InsufficientScope` enum and [error](cci:1://file:///Users/camillelawrence/Desktop/repos/apollo-mcp-server/crates/apollo-mcp-server/src/auth/www_authenticate.rs:135:4-149:5) field to `WWW-Authenticate` header
+- `valid_token.rs`: Extract [scope](cci:1://file:///Users/camillelawrence/Desktop/repos/apollo-mcp-server/crates/apollo-mcp-server/src/auth/valid_token.rs:27:0-38:1)/[scp](cci:1://file:///Users/camillelawrence/Desktop/repos/apollo-mcp-server/crates/apollo-mcp-server/src/auth/valid_token.rs:503:8-509:9) claims from JWTs (handles both standard OAuth and Azure AD)


The changeset documentation mentions handling both "scope" and "scp" claims for Azure AD, but the implementation only handles the standard "scope" claim. Azure AD uses "scp" for delegated permissions in access tokens, which is different from the standard OAuth "scope" claim. Consider either:

Removing the reference to "scp" and Azure AD from the documentation if Azure AD support via the "scp" claim is not needed, or

Adding support for the "scp" claim in the Claims struct and extract_scopes logic to actually support Azure AD tokens

Suggested change

- `valid_token.rs`: Extract [scope](cci:1://file:///Users/camillelawrence/Desktop/repos/apollo-mcp-server/crates/apollo-mcp-server/src/auth/valid_token.rs:27:0-38:1)/[scp](cci:1://file:///Users/camillelawrence/Desktop/repos/apollo-mcp-server/crates/apollo-mcp-server/src/auth/valid_token.rs:503:8-509:9) claims from JWTs (handles both standard OAuth and Azure AD)

- `valid_token.rs`: Extract [scope](cci:1://file:///Users/camillelawrence/Desktop/repos/apollo-mcp-server/crates/apollo-mcp-server/src/auth/valid_token.rs:27:0-38:1) claims from JWTs (standard OAuth scopes)

DaleSeo

Thanks for elaborating to address my feedback! I think the current implementation is good for now. We should be one of the early adopters and see how other MCP servers handle the ambiguous spec. Since this is related to security, I have one more suggestion to let users opt out of scope validation more explicitly, but I'll leave that up to you. I agree that we need to clearly document this scope validation behavior, regardless.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

gocamille force-pushed the AMS-171 branch from 18b4da5 to e5d2fe8 Compare January 7, 2026 17:19

gocamille marked this pull request as ready for review January 7, 2026 17:19

gocamille requested a review from DaleSeo January 7, 2026 17:19

gocamille requested a review from Copilot January 7, 2026 17:19

Copilot started reviewing on behalf of gocamille January 7, 2026 17:20 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

DaleSeo reviewed Jan 7, 2026

View reviewed changes

Comment thread .changeset/feat_add_insufficient_scope.md Outdated

Comment thread .changeset/feat_add_insufficient_scope.md Outdated

gocamille added 3 commits January 9, 2026 09:24

feat(auth): Add 403 Forbidden insufficient_scope support per MCP Auth…

97b3ada

… Spec 2025-11-25

feat: Add a changeset for insufficient_scope addition

9731df5

test(auth): add scope validation test coverage

3188f91

gocamille force-pushed the AMS-171 branch from c970c46 to 3188f91 Compare January 9, 2026 14:40

gocamille added 3 commits January 9, 2026 10:14

refactor(auth): remove Azure AD scp claim support

085979c

refactor(changeset): update changeset for invalid_scope feature

57ca974

fix cargo fmt errors

a6d1f6c

gocamille requested review from DaleSeo and Copilot January 9, 2026 15:17

Copilot started reviewing on behalf of gocamille January 9, 2026 15:18 View session

Copilot AI reviewed Jan 9, 2026

View reviewed changes

DaleSeo approved these changes Jan 9, 2026

View reviewed changes

Update .changeset/feat_add_insufficient_scope.md

bbe2f8a

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

gocamille merged commit 2354228 into main Jan 9, 2026
10 checks passed

gocamille deleted the AMS-171 branch January 9, 2026 18:55

github-actions Bot mentioned this pull request Jan 14, 2026

chore: prepare release 1.4.0 #556

Merged

	- `valid_token.rs`: Extract [scope](cci:1://file:///Users/camillelawrence/Desktop/repos/apollo-mcp-server/crates/apollo-mcp-server/src/auth/valid_token.rs:27:0-38:1)/[scp](cci:1://file:///Users/camillelawrence/Desktop/repos/apollo-mcp-server/crates/apollo-mcp-server/src/auth/valid_token.rs:503:8-509:9) claims from JWTs (handles both standard OAuth and Azure AD)
	- `valid_token.rs`: Extract [scope](cci:1://file:///Users/camillelawrence/Desktop/repos/apollo-mcp-server/crates/apollo-mcp-server/src/auth/valid_token.rs:27:0-38:1) claims from JWTs (standard OAuth scopes)

Conversation

gocamille commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Behavior

Uh oh!

apollo-librarian Bot commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview has no changes

Uh oh!

github-actions Bot commented Jan 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

DaleSeo Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

gocamille Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

DaleSeo Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

gocamille Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

DaleSeo Jan 9, 2026 • 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

DaleSeo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gocamille commented Jan 6, 2026 •

edited

Loading

apollo-librarian Bot commented Jan 6, 2026 •

edited

Loading

DaleSeo Jan 9, 2026 •

edited

Loading