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

Class McpAuthorizationCodeAcquirer

java.lang.Object
org.apache.juneau.rest.client.mcp.auth.McpAuthorizationCodeAcquirer
public class McpAuthorizationCodeAcquirer extends Object
Interactive authorization-code + PKCE (S256) token acquisition for headless / CLI use.

Builds on the relocated OAuthAuthorizationCodeFlow: opens a LoopbackRedirectReceiver, generates the state and PKCE code_verifier/code_challenge, hands the authorization URL to a caller-supplied browser launcher, waits for the loopback redirect, and exchanges the returned code for a token.

Security checks on the callback:

McpAuthorizationCodeAcquirer.Builder.resource(URI) (the RFC 8707 resource indicator) is required so the acquired token's audience is bound to the target MCP server.

The optional McpAuthorizationCodeAcquirer.Builder.offlineAccess(boolean) adds the offline_access scope so the IdP issues a refresh token that can subsequently drive an McpTokenProvider refresh-token provider (SEP-2207).

Since:
10.0.0

  • Constructor Details

  • Method Details

    • create

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

    • acquire

      public OAuthToken acquire(Duration timeout)
      Runs the full interactive acquisition: starts the loopback listener, opens the authorization URL, waits for the redirect, validates it, and exchanges the code for a token.
      Parameters:
      timeout - The maximum time to wait for the user to complete authorization at the IdP. Must not be null.
      Returns:
      The acquired token.
      Throws:
      McpAuthException - If the listener cannot start, the wait times out, or the callback fails validation.
      OAuthFlowException - If the token-exchange HTTP round-trip fails or the IdP returns an error.

    • buildAuthorizationUrl

      public URI buildAuthorizationUrl(OAuthAuthorizationCodeFlow flow, String state, com.nimbusds.oauth2.sdk.pkce.CodeVerifier verifier)
      Builds the authorization URL for a given state and PKCE verifier (exposed for callers driving their own user-agent interaction).
      Parameters:
      flow - The configured flow. Must not be null.
      state - The opaque state. Must not be null or blank.
      verifier - The PKCE verifier. Must not be null.
      Returns:
      The authorization URL.

    • handleCallback

      public OAuthToken handleCallback(OAuthAuthorizationCodeFlow flow, URI callbackUri)
      Validates a loopback callback and exchanges the authorization code for a token.

      Consumes the pending state entry (single-use), performs the SEP-2468 iss check against the issuer recorded when the request was started, then exchanges the code.

      Parameters:
      flow - The configured flow. Must not be null.
      callbackUri - The full loopback callback URI. Must not be null.
      Returns:
      The acquired token.
      Throws:
      McpAuthException - If the callback is an error response, the state is unknown/replayed, or the iss check fails.

    • validateAuthorizationResponse

      public static String validateAuthorizationResponse(URI callbackUri, String expectedState, URI expectedIssuer)
      Validates an authorization-code callback and returns the authorization code, without any token exchange or state-store interaction.

      This is the pure SEP-2468 / CSRF validation step. The iss comparison gates BOTH success and error responses (per the MCP spec a client MUST NOT act on an error/error_description/error_uri from a response whose iss does not match), so an error response with a mismatched issuer is reported as an issuer mismatch rather than a denial. A missing/mismatched state is rejected as CSRF. When iss is absent it is accepted (future-proofed for the eventual "reject if absent" MUST); use validateAuthorizationResponse(URI, String, URI, boolean) to require it.

      Parameters:
      callbackUri - The full callback URI. Must not be null.
      expectedState - The state issued when the authorization request was built. Must not be null.
      expectedIssuer - The discovered issuer to validate iss against. Must not be null.
      Returns:
      The authorization code.
      Throws:
      McpAuthException - If validation fails.

    • validateAuthorizationResponse

      public static String validateAuthorizationResponse(URI callbackUri, String expectedState, URI expectedIssuer, boolean requireIssuerParameter)
      Validates an authorization-code callback and returns the authorization code, without any token exchange or state-store interaction.
      Parameters:
      callbackUri - The full callback URI. Must not be null.
      expectedState - The state issued when the authorization request was built. Must not be null.
      expectedIssuer - The discovered issuer to validate iss against. Must not be null.
      requireIssuerParameter - true to reject a response that omits the iss parameter (RFC 9207 authorization_response_iss_parameter_supported).
      Returns:
      The authorization code.
      Throws:
      McpAuthException - If validation fails.