Skip to content

feat: add opt-in OAuth authentication for MCP - #2669

Open
erichare wants to merge 14 commits into
feat/mcp-protocol-2026-07-28from
fix/mcp-oauth-integration
Open

erichare wants to merge 14 commits into
feat/mcp-protocol-2026-07-28from
fix/mcp-oauth-integration

Conversation

@erichare

@erichare erichare commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

What this PR does:

Adds opt-in OAuth authentication and public discovery for MCP. Tool calls check the scope and database audience. Ordinary REST keeps its existing token headers. OAuth requires a JWT verifier at startup. Missing scope and database permission denials return distinct HTTP 403 challenges. Embedding and reranking use separate credentials.

Which issue(s) this PR fixes:

Part of #2642 and #2643. End-to-end OAuth is tracked in #2654. Builds on #2659. Full stack.

Verification

4,226 Java tests and 14 Python smoke-script tests passed on 4e44ab7d9 with JDK 21. Both legacy REST headers worked with strict inclusive authentication. With the verifier excluded, OAuth refused to start and legacy MCP still worked. Supported-client sign-in and public Astra authorization remain open in #2633 and #2634. Unit, DSE 6.9, and HCD CI passed.

./mvnw -o -B -ntp clean test -Dquarkus.http.test-port=19286
python3 -B -m unittest discover -s docs/mcp -p 'test_*.py'
Verifier startup check

The first command passed both legacy headers. The second stopped at startup with the expected message naming the required verifier.

./mvnw -o -B -ntp test -Dquarkus.http.test-port=19286 -Dquarkus.smallrye-jwt.enabled=false '-Dtest=McpOAuthDisabledTest#legacyMcpAuthenticationRemainsUsableWhenOAuthIsDisabled'
./mvnw -o -B -ntp test -Dquarkus.http.test-port=19286 -Dquarkus.smallrye-jwt.enabled=false '-Dtest=McpOAuthTest#validJwtListsToolsWithoutAStoredSession'

Checklist

  • Changes manually tested (earlier local database smoke)
  • Automated Tests added/updated
  • Documentation added/updated
  • CLA Signed: DataStax CLA

@erichare

erichare commented Nov 3, 2026

Copy link
Copy Markdown
Contributor Author

The November 3 alignment added deployment checks in #2634 for Authorization Bearer forwarding and database wake-up, plus permitted and denied database operations using the final identity contract, once agreed. #2654 tracks the gateway/platform and backend ownership needed for those checks.

The final subject and permission contract, token lifetime, and headless launch scope remain open. Resource-server acceptance of a JWT does not establish that the backend authorizes its identity correctly. Existing user-token behavior also needs to remain intact. These are integration dependencies alongside the local verification already recorded in this PR.

@erichare
erichare added this pull request to stack #2667 November 5, 2026 18:21
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

📈 Unit Test Coverage Delta vs Main Branch

Metric Value
Main Branch 57.12%
This PR 58.75%
Delta 🟢 +1.63%
✅ Coverage improved!

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Unit Test Coverage Report

Overall Project 58.75% -0.21% 🍏
Files changed 83.06% 🍏

File Coverage
PrincipalTokenResolver.java 100% 🍏
FixedTokenResolver.java 100% 🍏
DataApiAuthenticationPolicy.java 100% 🍏
ProtectedResourceMetadataResource.java 100% 🍏
HeaderBasedSecurityConfiguration.java 100% 🍏
EmbeddingTaskBuilder.java 100% 🍏
SyncServiceCredentialResolvingProvider.java 99.24% 🍏
McpEndpointConfigSourceFactory.java 99.16% 🍏
HeaderBasedAuthenticationMechanism.java 98.29% -0.34% 🍏
McpOAuthMetadata.java 96.2% -3.8% 🍏
FindAndRerankOperationBuilder.java 95% 🍏
McpOAuthScope.java 91.76% -8.24% 🍏
ErrorChallengeSender.java 85.34% 🍏
RerankingEGWClient.java 81.91% 🍏
McpResource.java 77.1% -13.42% ❌
EmbeddingGatewayClient.java 58.99% 🍏
RequestContext.java 54.1% -23.19% ❌
McpOriginFilter.java 41.98% -9.05% ❌
ValidateCredentials.java 13.1% -10.71% ❌
SyncServiceClient.java 2.4% -2.74% ❌
HeaderTokenResolver.java 0% 🍏
CollectionResource.java 0% -0.91% ❌

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

📉 Integration Test Coverage Delta vs Main Branch (hcd-it)

Metric Value
Main Branch 74.21%
This PR 73.68%
Delta 🔴 -0.54%
⚠️ Coverage decreased

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Integration Test Coverage Report (hcd-it)

Overall Project 73.68% -0.84% 🍏
Files changed 33.24% ❌

File Coverage
EmbeddingTaskBuilder.java 100% 🍏
DataApiAuthenticationPolicy.java 97.44% -2.56% 🍏
CollectionResource.java 96.8% 🍏
FindAndRerankOperationBuilder.java 95% 🍏
RequestContext.java 83.02% -8.37% 🍏
McpEndpointConfigSourceFactory.java 78.48% -1.27% 🍏
ErrorChallengeSender.java 77.31% -8.4% 🍏
McpResource.java 72.06% -13.7% ❌
PrincipalTokenResolver.java 68.42% -31.58% ❌
HeaderBasedAuthenticationMechanism.java 57.34% -41.3% ❌
McpOriginFilter.java 27.64% -8.94% ❌
HeaderBasedSecurityConfiguration.java 17.65% -82.35% ❌
McpOAuthMetadata.java 17.61% -82.39% ❌
ValidateCredentials.java 3.57% -23.81% ❌
SyncServiceClient.java 2.4% -2.74% ❌
McpOAuthScope.java 0% ❌
RerankingEGWClient.java 0% -6.38% ❌
FixedTokenResolver.java 0% 🍏
HeaderTokenResolver.java 0% 🍏
ProtectedResourceMetadataResource.java 0% ❌
EmbeddingGatewayClient.java 0% -3.79% ❌
SyncServiceCredentialResolvingProvider.java 0% -2.65% ❌

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

📉 Integration Test Coverage Delta vs Main Branch (dse69-it)

Metric Value
Main Branch 72.75%
This PR 72.24%
Delta 🔴 -0.51%
⚠️ Coverage decreased

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Integration Test Coverage Report (dse69-it)

Overall Project 72.24% -0.84% 🍏
Files changed 33.24% ❌

File Coverage
EmbeddingTaskBuilder.java 100% 🍏
DataApiAuthenticationPolicy.java 97.44% -2.56% 🍏
CollectionResource.java 96.8% 🍏
FindAndRerankOperationBuilder.java 85.21% 🍏
RequestContext.java 83.02% -8.37% 🍏
McpEndpointConfigSourceFactory.java 78.48% -1.27% 🍏
ErrorChallengeSender.java 77.31% -8.4% 🍏
McpResource.java 72.06% -13.7% ❌
PrincipalTokenResolver.java 68.42% -31.58% ❌
HeaderBasedAuthenticationMechanism.java 57.34% -41.3% ❌
McpOriginFilter.java 27.64% -8.94% ❌
HeaderBasedSecurityConfiguration.java 17.65% -82.35% ❌
McpOAuthMetadata.java 17.61% -82.39% ❌
ValidateCredentials.java 3.57% -23.81% ❌
SyncServiceClient.java 2.4% -2.74% ❌
McpOAuthScope.java 0% ❌
RerankingEGWClient.java 0% -6.38% ❌
FixedTokenResolver.java 0% 🍏
HeaderTokenResolver.java 0% 🍏
ProtectedResourceMetadataResource.java 0% ❌
EmbeddingGatewayClient.java 0% -3.79% ❌
SyncServiceCredentialResolvingProvider.java 0% -2.65% ❌

@erichare
erichare changed the base branch from fix/mcp-request-isolation to feat/mcp-protocol-2026-07-28 November 5, 2026 19:29
@erichare
erichare added this pull request to stack #2672 November 5, 2026 19:29
A deployment that serves one public host per database can now set
stargate.mcp.auth.public-host-suffix in place of the fixed public base
URL. The protected resource metadata, the 401 challenge and the
required aud claim are then built from the host of each request, so a
token issued for one database is rejected on another. A host outside
the suffix receives 401 without a challenge.

Bearer authentication now also requires mp.jwt.token.header to be
Authorization. Without a static audience list the built-in JWT
mechanism accepted a token from a cookie on REST paths with no
audience check.
An authorization server can list one resource per granted database in
aud. Check that such a token works on each listed database host and is
still challenged on a host it does not list.
@erichare
erichare force-pushed the fix/mcp-oauth-integration branch from 0f1f14b to b50eede Compare November 19, 2026 05:41
…ation

# Conflicts:
#	src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpResourceTest.java

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant