Build the authorization-request URL the host should open (browser/loopback).
GET an authorization URL (without following redirects) and extract the code query parameter from the Location response header.
GET an authorization URL (without following redirects), extract the code from the redirect Location header, and validate the RFC 9207 iss authorization-response parameter against the selected authorization server's recorded issuer (mix-up attack protection required by the MCP 2025-11-25 / draft authorization spec). Throws when iss is missing while authorization_response_iss_parameter_supported is true, or when it does not match the recorded issuer (simple string comparison, no normalization). The authorization code is NOT returned on rejection. When expectedState is non-empty, the redirect state parameter is also verified against it and the authorization code is discarded (a throw) when it is missing or mismatched, per the MCP "Open Redirection" guidance ("MCP clients SHOULD use and verify state parameters ... and discard any results that do not include or have a mismatch with the original state"). Passing an empty expectedState (the default) skips state verification.
Obtain a token via the client-credentials grant (service-to-service).
Use this client's configured OAuth Client ID Metadata Document URL (SEP-991) as the client_id for the authorization and token requests. The returned RegisteredClient carries the HTTPS-URL client_id and no secret, so it can be passed to authorizationUrl, exchangeCode, refresh, etc. exactly like a registered or pre-registered client.
Build the OAuth Client ID Metadata Document (SEP-991) this client should host at its clientIdMetadataUrl. The document's client_id is the URL itself and redirect_uris is the configured redirectUri.
Discover authorization-server metadata for an issuer, trying the RFC 8414 and OpenID Connect Discovery well-known locations in order.
Discover the protected-resource metadata for an MCP endpoint, using the resource_metadata URL from a WWW-Authenticate header when present, else the RFC 9728 well-known URLs in order.
Exchange an authorization code for tokens (PKCE auth-code grant).
RFC 7523 JWT-bearer grant: exchange an assertion JWT for an access token.
POST a tools/list request with a bearer token; if the server challenges with 401/403 (insufficient scope), return the WWW-Authenticate header. Used to detect step-up authorization requirements.
POST a minimal request to the MCP endpoint (optionally with a bearer token); if it returns 401, return the WWW-Authenticate header value (else empty). Used to trigger discovery and detect step-up challenges.
Refresh an access token.
Register a client dynamically (RFC 7591) at the AS registration endpoint.
Select the client-registration approach for an authorization server, per the spec priority order ("Client Registration Approaches"): pre-registration, then Client ID Metadata Documents (SEP-991), then Dynamic Client Registration, then prompting the user. havePreRegistered indicates the caller already holds a client_id for this AS.
Discover protected-resource metadata, falling back to treating the MCP server's origin as the issuer when no PRM document exists (the pre-RFC-9728 2025-03-26 behavior). Returns the issuer to use for AS discovery, and sets fromProtectedResourceMetadata to true on the modern RFC 9728 path or false on the 2025-03-26 origin fallback (the issuer enforcement implications of each path are documented on bindDiscoveredIssuer).
Convenience overload that discards the discovery-source signal.
RFC 8693 token exchange: swap a subject token (e.g. an IdP id_token) for a requested token type (e.g. an ID-JAG assertion) at tokenEndpoint. Rejects an empty resource — see the class docstring for the rationale.
How to authenticate at the token endpoint.
SEP-991: this client's OAuth Client ID Metadata Document URL — an HTTPS URL (with a path component) at which the client hosts its metadata document. When set and the authorization server advertises client_id_metadata_document_supported, this URL is used directly as the client_id (no Dynamic Client Registration needed).
EC private key (PKCS#8 PEM) for private_key_jwt client assertions.
The client's redirect URI for the auth-code flow.
The canonical resource indicator (the MCP server URL). MANDATORY for the MCP authorization/token flows: per RFC 8707 the resource indicator MUST be sent on the authorization and token requests regardless of whether the authorization server advertises support, so authorizationUrl, exchangeCode, refresh, clientCredentials, tokenExchange, and jwtBearerGrant reject an empty value. useOAuth sets this to the canonical MCP server URI automatically.
A production OAuth 2.1 client for MCP: drives protected-resource and authorization-server metadata discovery (RFC 9728 / RFC 8414), Dynamic Client Registration (RFC 7591), and the token endpoint (authorization-code + PKCE, client-credentials, refresh) with RFC 8707 resource indicators.
The interactive authorization-code redirect (opening a browser / running a loopback listener) is supplied by the host application via an authorizeCallback; everything else is handled here.