Skip to content

OAuth Metadata Discovery should respect provided Authorization Server URL before applying RFC 8414 path construction #744

Closed

Description

@katesclau

OAuth Metadata Discovery Should Respect Provided Authorization Server URL Before Applying RFC 8414 Path Construction

Description

The current OAuth metadata discovery implementation in src/client/auth.ts 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 don't fully comply with RFC 8414 path construction but provide working endpoints.

Expected Behavior

When an authorization server URL is provided in the resource metadata (e.g., authorization_servers: ['http://localhost:9090/realms/mcp']), the SDK should:

  1. First attempt discovery at the exact provided URL + /.well-known/oauth-authorization-server
  2. Only if that fails, then attempt RFC 8414 path-aware discovery patterns
  3. Finally fall back to root discovery as currently implemented

Current Behavior

The SDK immediately applies RFC 8414 path-aware discovery, constructing URLs like:

http://localhost:9090/.well-known/oauth-authorization-server/realms/mcp

This fails with Keycloak and other authorization servers that don't implement RFC 8414 path-aware discovery but do provide working endpoints at the standard location.

Reproduction Steps

  1. Set up an authorization server that provides metadata with authorization_servers: ['http://example.com/realms/test']
  2. Ensure the server has a working endpoint at http://example.com/realms/test/.well-known/oauth-authorization-server
  3. Run OAuth discovery with the TypeScript SDK
  4. Observe that it tries http://example.com/.well-known/oauth-authorization-server/realms/test (404) instead of the working endpoint

Environment

Relevant Code

The issue appears to be in discoverOAuthMetadata() function in src/client/auth.ts around lines 370-390, where path-aware discovery is attempted first without trying the direct URL.

Proposed Solution

Modify the discovery order in discoverOAuthMetadata() to:

  1. Try direct URL: ${authorizationServerUrl}
  2. Try path-aware (current first attempt): ${origin}/.well-known/oauth-authorization-server${pathname}
  3. Try root fallback (current second attempt): ${origin}/.well-known/oauth-authorization-server

This would maintain RFC 8414 compliance while being more practical for real-world authorization servers.

Additional Context

This issue affects interoperability with common authorization servers like Keycloak that provide functional OAuth metadata endpoints but don't implement the full RFC 8414 specification. The current implementation prioritizes strict RFC compliance over practical functionality.

Related Issues

This issue is related to but distinct from #616, which addresses falling back to .well-known/openid-configuration when .well-known/oauth-authorization-server fails entirely (e.g., with Google's authorization server).

The issues are complementary:

Both issues aim to improve compatibility with real-world authorization server implementations that don't fully conform to RFC 8414.


Note: I've searched existing issues and found the related issue #616 mentioned above. This follows the project's contributing guidelines for providing clear reproduction steps and context.

Activity

  1. pcarleton commented on Jul 14, 2025

    @pcarleton
    Member

    Are there are other servers aside from Keycloak that you know of that have this problem? I wonder if fixing keycloak to support RFC 8414 would be a viable solution.

  2. katesclau commented on Jul 14, 2025

    @katesclau
    Author

    Hey @pcarleton , thanks for the response. Yes, it is a way of solving this - see keycloak/keycloak#40923 (comment)

    But, regardless, when provided with a specific endpoint for authorization server, the client should check it contains the required information, specially if the URL provided as authorization server contains the .well-known/oauth-authorization-server in it. But I'm opened to discussion 😄

  3. MTG2000 commented on Jul 16, 2025

    @MTG2000

    We are also facing the same problem where we are using WorkOS and it returns the metadata on https://something.authkit.app/.well-known/oauth-authorization-server but since our mcp is on a /mcp pathname, the SDK is attempting to find the metadata on https://something.authkit.app/.well-known/oauth-authorization-server/mcp and it's failing with 404

    I think the problem is happening here:

    async function discoverMetadataWithFallback(

    The metadataUrl in opts is being ignored it seems in our case when the function is called with args:

    serverUrl = URL (with a pathname)
    wellKnownType = "oauth-authorization-server"
    opts = { metadataServerUrl: URL (without the pathname) }
    

    Is this the expected behaviour or is it a bug?

  4. jpmcb commented on Jul 21, 2025

    @jpmcb

    Also facing the same problem with Okta based Oauth servers:

    ❯ curl localhost:9000/.well-known/oauth-protected-resource
    
    {
      "resource": "http://localhost:9000",
      "authorization_servers": [
        "https://my-org.okta.com/oauth2/abc123"
      ],
      "resource_name": "My MCP OAuth Resource"
    }
    

    Okta OAuth resource servers are namespaced like: https://{yourOktaDomain}/oauth2/{authorizationServerId}.

    This SDK creates the metadata as with the trailing metadata:

    https://my-org.okta.com/.well-known/oauth-authorization-server/oauth2/abc123
    

    which is invalid and results in a 405.


    Note: this directly affects testing servers with MCP inspector as well: modelcontextprotocol/inspector#634

  5. pcarleton commented on Jul 23, 2025

    @pcarleton
    Member

    We're in the process of adding support for openid-configuration as a valid metadata endpoint. OIDC config. As part of supporting that, we need to check appending .well-known/openid-configuration after the path.

    Here's how it will look for an authorization_servers: ["https://auth.example.com/oauth"] PRM entry:

    1. https://auth.example.com/.well-known/oauth-authorization-server/oauth
    2. https://auth.example.com/.well-known/oauth-authorization-server
    3. https://auth.example.com/.well-known/openid-configuration/oauth
    4. https://auth.example.com/oauth/.well-known/openid-configuration

    @jpmcb , @katesclau Will that work for both of these use cases?

    Here's the PR for that:
    #652

  6. katesclau commented on Jul 23, 2025

    @katesclau
    Author

    Here's how it will look for an authorization_servers: ["https://auth.example.com/oauth"] PRM entry:

    1. https://auth.example.com/.well-known/oauth-authorization-server/oauth
    
    2. https://auth.example.com/.well-known/oauth-authorization-server
    
    3. https://auth.example.com/.well-known/openid-configuration/oauth
    
    4. https://auth.example.com/oauth/.well-known/openid-configuration
    

    Will that work for both of these use cases?

    In this case, nothing changes for the .well-known/oauth-authorization-server discovery? the provided path will be added only after the .well-known/oauth-authorization-server, as currently is? If yes, I think it won't solve the existing issues with Okta and Keycloak - but I can test it to validate 😉

    I understand the current release implements RFC 8414 compliant, but the same RFC also suggest implementation of both patterns for compatibility.
    ie.: for authorization_servers: ["https://auth.example.com/oauth"]

    1. https://auth.example.com/.well-known/oauth-authorization-server/oauth //RFC 8414 compliant
    2. https://auth.example.com/oauth/.well-known/oauth-authorization-server //RFC 8414 suggested
    3. https://auth.example.com/.well-known/oauth-authorization-server
    4. https://auth.example.com/.well-known/openid-configuration/oauth
    5. https://auth.example.com/oauth/.well-known/openid-configuration

    Thanks @pcarleton for the attention on this matter ❤️

  7. pcarleton commented on Jul 24, 2025

    @pcarleton
    Member

    Hi it seems like this will work for Okta (just setup a trial account):
    https://trial-4583365.okta.com/oauth2/default/.well-known/openid-configuration

    and seems to work with keycloak as well:
    curl http://localhost:8080/realms/master/.well-known/openid-configuration

  8. pcarleton commented on Jul 24, 2025

    @pcarleton
    Member

    Going to close this since it seems like the open ID compatibility work in this PR should fix it, but lmk if that's incorrect:
    #652

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions