issue/744 - Uses authorization server url provided by .well-known/oauth-protected-resource metadata

[katesclau]

Fix OAuth metadata discovery to respect provided authorization server URLs (issue 744)

Summary

Fix OAuth metadata discovery to respect provided authorization server URLs before applying RFC 8414 path construction. This change modifies the discovery order to try the exact provided URL first, then fall back to RFC 8414 path-aware discovery patterns.

Motivation and Context

The current OAuth metadata discovery implementation automatically applies RFC 8414 path-aware discovery patterns to authorization server URLs without first attempting to use the exact URL provided in the metadata. This causes failures when working with authorization servers like Keycloak that provide functional OAuth metadata endpoints but don't implement the full RFC 8414 specification.

Problem: When a server provides authorization_servers: ['http://localhost:9090/realms/mcp-rtlm'], the SDK would immediately try path-aware URLs like http://localhost:9090/.well-known/oauth-authorization-server/realms/mcp-rtlm instead of first attempting the provided URL directly.

Impact: This breaks compatibility with common authorization servers that provide working endpoints but don't follow RFC 8414 path construction patterns.

How Has This Been Tested?

• ✅ Unit tests updated: All existing tests pass with the new discovery order
• ✅ New test scenarios: Added comprehensive test coverage for the updated discovery flow
• ✅ Real-world testing: Tested with Keycloak integration in mcp-rtlm project where this issue was discovered
• ✅ Edge cases: Tested fallback behavior when direct URLs fail (404, CORS errors)
• ✅ Backward compatibility: Verified existing OAuth flows continue to work

Test scenarios covered:

1. Direct issuer URL succeeds immediately
2. Direct URL fails → path-aware discovery succeeds
3. Both direct and path-aware fail → root discovery succeeds
4. CORS error handling with proper retry logic
5. All discovery methods fail gracefully

Breaking Changes

❌ No breaking changes. This is purely an internal optimization that improves compatibility. The public API remains unchanged and existing code will continue to work as expected.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Implementation Details

New Discovery Order (in discoverOAuthMetadata):

1. Try provided issuer URL directly - respects server's explicit metadata
2. Try path-aware discovery - RFC 8414 compliant fallback
3. Try root discovery - final fallback for maximum compatibility

Files Modified:

• src/client/auth.ts: Updated discovery logic in discoverOAuthMetadata
• src/client/auth.test.ts: Updated tests to match new behavior

Design Decisions

• Backward compatibility: Preserved all existing fallback mechanisms
• Error handling: Maintained existing CORS retry logic and error propagation
• Performance: No additional network calls - same total number of attempts
• RFC compliance: Still follows RFC 8414 patterns as fallbacks while respecting explicit server URLs

Related Issues

This addresses compatibility issues with authorization servers that provide working OAuth metadata endpoints at non-RFC-8414-compliant paths, particularly affecting integrations with Keycloak and similar enterprise identity providers.

[katesclau]

we could also validate if the issuer URL already contains .well-known/oauth-authorization-server string 🤔

[ochafik]

Hi @katesclau , thanks for sending this out!

It's not clear to me that we should go down this route tbh.

RFC 9728 (which governs the oauth-protected-resource) defines authorization_servers as:

containing a list of OAuth authorization server issuer identifiers, as defined in RFC8414

RFC8414 states that an issuer identifier is:

a URL that uses the "https" scheme and has no query or fragment components`.

Sounds like maybe an issue to submit to Keycloak's consideration, not sure what the best way forward on their end is but I'd rather the SDK followed the RFCs.

[katesclau]

Hi @katesclau , thanks for sending this out!

It's not clear to me that we should go down this route tbh.

RFC 9728 (which governs the oauth-protected-resource) defines authorization_servers as:

containing a list of OAuth authorization server issuer identifiers, as defined in RFC8414

RFC8414 states that an issuer identifier is:

a URL that uses the "https" scheme and has no query or fragment components`.

Sounds like maybe an issue to submit to Keycloak's consideration, not sure what the best way forward on their end is but I'd rather the SDK followed the RFCs.

We already have an issue opened on Keycloak with this discussion, but regardless, the authorization servers list is ignored if it contains the actual endpoint for oauth-protected-resource. I understand that the proposed solution is not RFC8414 compliant, but this solves multiple cases, as illustrated on #744.

Feel free to close the PR if you don't think this is a viable solution.

[pcarleton]

going to close this as the openID compatibility work should cover this:
#652