Package org.apache.juneau.rest.client.mcp.auth

Class McpProtectedResourceMetadataClient

java.lang.Object
org.apache.juneau.rest.client.mcp.auth.McpProtectedResourceMetadataClient
public class McpProtectedResourceMetadataClient extends Object
Fetches and parses an RFC 9728 Protected Resource Metadata (PRM) document, and resolves the authorization server a protected MCP resource delegates to.

This is the client half of the OAuth 2.1 baseline PRM discovery required by the MCP 2026-07-28 revision: on a 401 WWW-Authenticate challenge the client recovers the resource_metadata pointer (WwwAuthenticateChallenge.resourceMetadata()), fetches the PRM document here, selects an authorization server (McpProtectedResourceMetadata.firstAuthorizationServer()), and validates that server's issuer identity via OidcDiscoveryClient (RFC 8414 / OIDC Discovery).

When an expected resource identifier is supplied (McpProtectedResourceMetadataClient.Builder.expectedResource(URI) or the expectedResource argument of fetch(URI, URI) / parse(String, URI, URI)), the PRM document's resource field is validated against it per RFC 9728 §3.3 (exact string match, mirroring the issuer-identity posture) and a mismatch is rejected — this defends against a malicious server pointing the client at a PRM document minted for a different resource. When no expected resource is supplied the identity check is skipped.

By default the PRM URL and any discovered authorization-server URI must use https (loopback hosts are always permitted for local/testing use); McpProtectedResourceMetadataClient.Builder.allowInsecureHttp(boolean) disables the scheme check entirely.

Since:
10.0.0

  • Constructor Details

  • Method Details

    • create

      public static McpProtectedResourceMetadataClient.Builder create()
      Static creator.
      Returns:
      A new builder.

    • fetch

      public McpProtectedResourceMetadata fetch(URI prmUrl)
      Fetches and parses the PRM document at the supplied URL, validating its resource field against the builder-configured McpProtectedResourceMetadataClient.Builder.expectedResource(URI) (if any).
      Parameters:
      prmUrl - The PRM document URL (typically the resource_metadata pointer from a 401 challenge, or the well-known URL for the resource). Must not be null.
      Returns:
      The parsed metadata.
      Throws:
      McpAuthException - If the fetch fails, the document cannot be parsed, or the resource identity check fails.

    • fetch

      public McpProtectedResourceMetadata fetch(URI prmUrl, URI expectedResource)
      Fetches and parses the PRM document at the supplied URL, validating its resource field against the supplied expected resource identifier (RFC 9728 §3.3).
      Parameters:
      prmUrl - The PRM document URL. Must not be null.
      expectedResource - The resource identifier the client was actually talking to. May be null to skip the identity check.
      Returns:
      The parsed metadata.
      Throws:
      McpAuthException - If the fetch fails, the document cannot be parsed, or the resource identity check fails.

    • parse

      public McpProtectedResourceMetadata parse(String json, URI source)
      Parses a PRM JSON document body, validating its resource field against the builder-configured McpProtectedResourceMetadataClient.Builder.expectedResource(URI) (if any).
      Parameters:
      json - The JSON document body. Must not be null.
      source - The source URI, used only for error messages. May be null.
      Returns:
      The parsed metadata.
      Throws:
      McpAuthException - If the document cannot be parsed, is missing the required resource field, or fails the resource identity check.

    • parse

      public McpProtectedResourceMetadata parse(String json, URI source, URI expectedResource)
      Parses a PRM JSON document body, validating its resource field against the supplied expected resource identifier (RFC 9728 §3.3).
      Parameters:
      json - The JSON document body. Must not be null.
      source - The source URI, used only for error messages. May be null.
      expectedResource - The resource identifier the client was actually talking to. May be null to skip the identity check.
      Returns:
      The parsed metadata.
      Throws:
      McpAuthException - If the document cannot be parsed, is missing the required resource field, or fails the resource identity check.

    • discoverAuthorizationServer

      public OidcMetadata discoverAuthorizationServer(McpProtectedResourceMetadata prm)
      Selects the first authorization server from the PRM document and validates its issuer identity via RFC 8414 / OIDC discovery.
      Parameters:
      prm - The parsed PRM document. Must not be null.
      Returns:
      The discovered authorization-server metadata (issuer validated).
      Throws:
      McpAuthException - If no authorization server is advertised or discovery/issuer validation fails.