MCP: Test OAuth sign-in with supported clients #2633

Tracking issue: #2408. Depends on #2624, #2625, #2642 and an implemented authorization-service contract.

Tracking correspondence: H1–H7 and L3. Full OAuth and independent-client verification. Shared requirement IDs remain stable across the delivery plan and #2408.

Outcome

Qualify the modern protocol and complete OAuth flow with an independently implemented client. Support is vendor-neutral. Include IBM Bob and other relevant hosts in the release matrix without naming one primary client or claiming untested versions work.

Protocol and host qualification

• Pin an official SDK build with verified 2026-07-28 support. Record exact host/SDK/build versions and supported protocol revisions. Do not infer support from a product name or its latest release.
• Exercise server/discover, complete tool listing/pagination, direct first request without discovery, an authorized read, a known application error and a successful subsequent call. Verify resultType, cache hints, structured output and usable result visibility.
• Maintain rows for IBM Bob and relevant hosts such as Gemini Enterprise, Claude and Cursor. Mark each as passed, failed or not yet tested, with registration/redirect mode and evidence. A host missing the modern protocol or OAuth support needs an upgrade before connecting.
• Exercise stream disconnect handling if streaming is enabled. Retries need new request IDs and must not blindly replay mutations.

OAuth qualification

Exercise the bearer-token integration from Data API PR #2617 with the final authorization-server contract. Record the exact implementation revision and verification configuration. The current resolver change alone does not prove an end-to-end OAuth flow.

• Start without credentials, parse the 401 challenge, fetch protected resource metadata and discover the authorization server using RFC 8414 and OIDC Discovery cases, including path-aware issuer URLs.
• Reject metadata issuer mismatch and missing PKCE-support metadata. Verify S256, resource on authorization and token requests, exact redirect/transaction binding and consent denial.
• Use pre-registration or CIMD. Validate CIMD identifier/document agreement and redirect restrictions. If DCR is explicitly supported, require native/web application_type and test only that approved path.
• Record the validated expected issuer before redirect. If iss is present, always compare it exactly before code exchange, even if support is unadvertised. If support is advertised true and iss is absent, reject. If both advertisement and iss are absent, this revision permits continuing. Test success and error callbacks without URL normalization.
• Key issuer-issued registration credentials by issuer and never reuse them across authorization servers. A CIMD URL identifier is portable, which is distinct from issuer-issued credentials.
• Validate authorized scope/tenant access and 401 versus 403 behavior. Reject ID tokens, AstraCS tokens and old custom token headers at MCP. Test refresh or reauthorization, revoked access and safe bounded step-up retries.
• A locally issued test token can support protocol-only tests, but cannot substitute for a completed browser authorization flow in launch evidence.

Done when

One documented read-only-by-default command runs against the packaged release candidate with the integrated authorization service and is reusable against deployed servers using external configuration and redacted output. A reusable auth harness covers protocol edge cases that host UIs cannot inject. The matrix records actual results for each launch-supported client, including IBM Bob. Unverified clients remain explicit gaps, not implicit successes.

#2634 owns replaying the same client and policy through the deployed edge. Close this ticket on packaged qualification and the recorded client matrix, without waiting for deployment approval. #2627/#2628 remain separately tracked usability/error work and become gates when required for a qualified client.

Changelog traceability

• M3 Implement server discovery, lines 16 — Required.
• M7 Use multi round trip requests, lines 24 — Conditional.
• M9 Remove stream redelivery, lines 28 — Required.
• m3 Return tools in stable order, lines 34 — Recommended.
• m7 Validate authorization response issuer, lines 38–41 — Required auth.
• m8 Set registration application type, lines 42–44 — Conditional auth.
• m9 Scope registration credentials to issuer, lines 45–48 — Required auth.
• D4 Prefer client metadata documents over DCR, lines 93–99 — Required auth decision.

Normative detail: Streamable HTTP, authorization, caching.

Discovery fixtures

Capture the URLs requested and their order. Prefer the resource_metadata URL from the parsed WWW-Authenticate challenge when present. Without that URL, try path-specific protected resource metadata and then root metadata. For an MCP endpoint at /v1/mcp, those fallback paths are /.well-known/oauth-protected-resource/v1/mcp and /.well-known/oauth-protected-resource.

Exercise authorization-server discovery in the following order. Each row uses paths on the selected issuer's host. Make earlier locations unavailable in turn to exercise every fallback.

Reject resource-identifier mismatches and metadata whose issuer differs from the expected issuer before using its endpoints. Include trailing-slash differences. Compare exact values without URL normalization.

Exercise the existing credential-isolation requirement using two issuers and a change to the issuer advertised in resource metadata. Verify that issuer-issued credentials and tokens are never reused with the other issuer. Preserve the existing exception for portable CIMD identifiers. These fixtures do not require multiple production authorization servers.

Link the companion authorization-service owner and contract reference recorded in #2408. Record which metadata mechanism that service publishes and verify its actual public URL during integration.

See MCP discovery, RFC 9728 section 3.3, RFC 8414 sections 3.3–4, OIDC section 4.3, and authorization-server binding.