Repository navigation
Track the complete MCP OAuth flow #2654
Description
A supported client should connect without credentials, discover how to sign in, receive consent, and make an authorized MCP call. It should also recover when access expires or permissions change.
This tracks the complete OAuth flow under the MCP launch. Each piece needs an accountable owner, an implementation ticket, and passing verification. Existing tickets retain their implementation and verification scope.
Status on November 3, 2026
PR #2669 is the current Data API authentication and discovery proposal. The local demonstration showed 9/9 checks for health, discovery, a client-credentials token exchange and authenticated MCP initialization. No database operation was shown in those checks. Initialization also does not qualify the sessionless protocol required by #2624. Keep that demo separate from the database smoke evidence recorded on #2669.
The demonstrated client-secret headless flow uses an application-held AstraCS credential to obtain an MCP access JWT. Confirm the service-client identity and role-restriction contract with the authorization-service and backend owners. The final claims, permission mapping and lifetime remain open.
Headless launch scope remains unresolved for both client-secret authentication and signed JWT assertions. The client-credentials extension is optional in MCP. If assertions are selected, key registration and trust need a design. Supported client requirements need confirmation in #2633. Headless launch scope and delivery timing still need confirmation.
Work to track
| Piece | Tracking and ownership | Completion evidence |
|---|---|---|
| Agree the authorization service and its contract | Needs a named owner and implementation reference. Coordinate with #2642 and #2633. | Record the trusted issuer, canonical MCP resource URL, token format, subject identity, validation method, scopes, tenant/database permissions, access-token lifetime, credential expiration, and renewal policy. Link the agreed contract revision. |
| Discover the protected MCP resource | Data API implementation in #2642. | Clients can fetch resource metadata without credentials. A 401 Bearer challenge points to that metadata, which identifies the resource and trusted authorization server. |
| Discover the authorization service | Needs an authorization-service implementation ticket and owner. | Publish OAuth authorization-server metadata or OpenID Connect discovery. Verify the issuer, authorization and token endpoints, and advertised PKCE support. |
| Identify or register the client | Needs an authorization-service implementation ticket and owner. | Support agreed pre-registration and Client ID Metadata Documents. Define permitted redirect URLs and isolate issuer-issued credentials by issuer. Track dynamic registration only if explicitly supported. |
| Complete sign-in and consent | Needs authorization-service and client integration ownership. | Complete the authorization code flow with PKCE S256, resource binding, exact redirect checks, and transaction binding. Verify consent denial and callback issuer validation on success and error. |
| Issue a token and authorize MCP calls | Authorization service issues tokens. Data API enforcement is #2642. | Validate authenticity, issuer, audience, expiry, scopes, and organization/database/operation permissions. Reject ID tokens, AstraCS tokens, and legacy MCP token headers. Verify 401 and 403 responses. |
| Resolve downstream credentials and backend identity | Data API work in #2642 with authorization-service and backend/coordinator owners. Named external owners and implementation references remain needed. | Agree the service-client identity and permission mapping. Preserve existing user-token behavior and prove permitted and denied database operations with issued tokens. Keep incoming MCP and unrelated provider credentials separate. |
| Forward Bearer tokens and resume databases | Gateway/platform work with Data API. Named owner and implementation reference remain needed. Verify deployment in #2634. | Recognize and forward Authorization through the public endpoint, route to the correct database and wake it from hibernation. Verify authorized and denied calls after wake-up. |
| Decide headless launch scope | Authorization-service/security and product owners, with client qualification in #2633. Named decision owner remains needed. | Record supported unattended flows and explicit deferrals. If assertions are selected, define public-key enrollment and trust. Keep client assertions distinct from issued MCP access tokens. |
| Renew or withdraw access | Needs an authorization-service implementation ticket and owner, coordinated with #2642. | Verify refresh or reauthorization, expiration, revocation, key rotation, permission changes, and bounded requests for additional scopes. |
| Prove the complete client flow | #2633 covers clients. #2626 covers HTTP behavior. | Record exact client and SDK builds, including IBM Bob. Start without credentials and complete discovery, consent, an authorized call, denial, and recovery. |
Release dependencies
#2630 verifies browser origins. #2635 protects payloads and credentials in logs. #2643 publishes connection and migration instructions. #2634 repeats the flow through the public deployment and verifies rollout readiness. The protocol implementation remains in #2625.
Completion
Close this tracker when every OAuth piece has an owner and linked implementation evidence, supported clients pass the complete flow, and deployed verification and connection instructions are complete. Keep missing implementation tickets and untested clients visible until they have evidence.
The policy is recorded in #2624. Review coverage against the MCP authorization specification, including its discovery, client registration, and security requirements. Keep private service details in approved private records and link a public-safe reference here.
Activity