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

Class McpStepUpAuthorizer

java.lang.Object
org.apache.juneau.rest.client.mcp.auth.McpStepUpAuthorizer
public class McpStepUpAuthorizer extends Object
Client-side SEP-2350 step-up state machine: wraps an MCP call so that, on a 401/403 insufficient_scope challenge, it computes the required-scope union (McpScopeAccumulator), drives (re-)authorization via a caller-supplied McpStepUpAuthorizer.Reauthorizer, and retries the original call — bounded by a hard attempt cap with per-(resource, operation) attempt tracking so a misconfigured server can't drive an unbounded re-authorization loop (spec "no more than a few times").

Step-up for user-delegation clients is inherently interactive (a fresh auth-code + PKCE round-trip), so this is an explicit orchestration helper the caller wraps around MCP calls — not a silent interceptor retry. The caller's McpStepUpAuthorizer.ScopedCall performs the actual MCP request and throws McpInsufficientScopeException (carrying the parsed WwwAuthenticateChallenge) when the server responds with a step-up challenge; the McpStepUpAuthorizer.Reauthorizer performs the (re-)authorization with the widened scope union (e.g. via McpAuthorizationCodeAcquirer for user clients or a client-credentials re-acquire) and installs the new token.

client_credentials (own-behalf) clients MAY abort immediately rather than attempt step-up (attemptStepUp(false)).

Attempt-counter lifetime

Per-(resource, operation) attempt counts exist only to bound a single step-up burst. A counter is cleared automatically when execute returns successfully for that operation, so a long-lived authorizer does not permanently refuse a later legitimate step-up for the same operation. A counter that reaches the cap without a success (a permanent failure) is not auto-cleared — the caller can reset it explicitly with reset(String) (one operation) or resetAll() (all operations) once the underlying cause is resolved.

Since:
10.0.0

  • Constructor Details

  • Method Details

    • create

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

    • execute

      public <T> T execute(String operation, McpStepUpAuthorizer.ScopedCall<T> call)
      Executes an MCP call, transparently handling SEP-2350 step-up: on an insufficient_scope challenge it unions the challenge scopes onto the accumulated set, re-authorizes, and retries — up to the configured attempt cap, after which it throws a permanent McpAuthException.
      Type Parameters:
      T - The call result type.
      Parameters:
      operation - The operation identifier (e.g. tools/call:deploy) used for per-operation attempt tracking. Must not be null or blank.
      call - The MCP call. Must not be null.
      Returns:
      The successful call result.
      Throws:
      McpAuthException - If step-up is disabled, or the attempt cap is exceeded (permanent authorization failure).

    • attempts

      public int attempts(String operation)
      Returns the number of step-up attempts recorded for the given operation.
      Parameters:
      operation - The operation identifier. Must not be null or blank.
      Returns:
      The recorded attempt count.

    • reset

      public void reset(String operation)
      Clears the recorded step-up attempt count for a single operation (e.g. after the caller has resolved the cause of a prior permanent failure), so a subsequent execute(String, ScopedCall) may step up again.
      Parameters:
      operation - The operation identifier. Must not be null or blank.

    • resetAll

      public void resetAll()
      Clears all recorded step-up attempt counts for this authorizer's resource across every operation.