Title: OAuth client: refresh before re-authorizing, and discover before refreshing by maxisbey · Pull Request #3328 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: OAuth client: refresh before re-authorizing, and discover before refreshing by maxisbey · Pull Request #3328 · modelcontextprotocol/python-sdk
X Title: OAuth client: refresh before re-authorizing, and discover before refreshing by maxisbey · Pull Request #3328 · modelcontextprotocol/python-sdk
Description: On a 401, OAuthClientProvider now tries the stored refresh token (after rediscovery) before falling back to interactive authorization, and the pre-request refresh only runs once authorization-server metadata is known, so it never guesses {origin}/token. A restarted or headless client with a persisted refresh token recovers from an expired access token without a browser. Closes #3240, closes #3250, closes #1318. Motivation and Context The provider had two ways to obtain a token that each lacked half of what they needed: the pre-request branch could refresh but never ran discovery, and the 401 branch ran discovery but never tried the refresh token. After a restart nothing restores an expiry, so the pre-request branch is skipped, the stale bearer draws a 401, and the flow goes to the browser with a usable refresh token in hand — headless clients just fail. If an application forced the pre-request path by reporting the loaded token as expired, the refresh went to a path derived from the server origin, which 404s for any authorization server under a path, and the refresh token was then discarded. #1318 reported this a year ago; #3240 and #3250 are the same defect from two angles. The 401 branch did refresh in 1.10/1.11; #1071 moved that block ahead of the request instead of duplicating it and nothing tested the restart path. What changed 401 branch, Step 5: if can_refresh_token(): refresh → on success retry the request; otherwise (no refresh token, or the server rejected it) run the full grant as before. Pre-request refresh: additionally gated on oauth_metadata is not None. In-process behaviour is unchanged (metadata is cached after the first flow); on a cold start the request goes out and the 401 branch discovers, then refreshes. A failed refresh (either site) resets _initialized inside _handle_refresh_response, so the next request re-reads storage; a long-lived headless provider whose one refresh hit a transient error retries it rather than staying tokenless for the life of the process. Classifying failures (keep the refresh token on 5xx, clear only on invalid_grant) is left for the follow-up below. A fresh dynamic registration clears any held tokens (they were issued to a previous client and can't be refreshed by the new one). A CIMD client_id is portable across authorization servers, but tokens issued under it are not: when the issuer that becomes known (from PRM, or from AS metadata on the legacy no-PRM path) differs from the record's SEP-2352 stamp — or the record carries no stamp, so its tokens have no confirmed origin — the record is kept and re-stamped and its tokens (and any cached metadata from the previous server) are dropped before anything is refreshed (the TypeScript SDK's discardIfIssuerMismatch). The existing bound-credential discard and this rule now live in one _apply_issuer_binding method called at both points the issuer becomes known, replacing the two inline copies. src/ is +55/−41. No public API change, TokenStorage untouched. This is the TypeScript SDK's ordering (auth() refreshes before startAuthorization) and matches C#/Rust. How Has This Been Tested? Interaction tests against the SDK's own AS+RS in process, each logging in as a "first process" and then connecting a fresh provider over the same storage: refresh on 401 after restart (no handlers wired); the same against an AS mounted under /oauth2/v1 (bare /token 404s) proving the refresh goes to the advertised endpoint; a rejected 401-path refresh falling back to authorization; a headless provider retrying the refresh on its next connection after a failed one; a fresh registration not presenting tokens left from a previous client; and a CIMD client keeping its id but dropping its tokens on an issuer change. Each was mutation-checked against the line it pins. Unit tests pin that an expired token is not refreshed ahead of the request while metadata is unknown, and the CIMD rebinding on both discovery paths (stamped elsewhere, and unstamped). Manifest gains client-auth:refresh:on-401 and client-auth:refresh:discovered-endpoint; the harness gains a path-prefixed-AS shim and expire_access_token. Also driven over real sockets (uvicorn serving the SDK AS with 3 s access tokens, then under a prefix; a separate application process with file-backed storage run repeatedly): headless runs after expiry show 401 → PRM → ASM → POST …/token grant_type=refresh_token → 200; with tokens.json rewritten to expires_in=-1 and an app that derives expiry on load (the #3240 setup) there is no guessed /token request and the refresh lands on /oauth2/v1/token. Breaking Changes None. Behavioural notes: a 401 with a refresh token in storage now produces one token-endpoint request before any redirect (a scope= challenge wider than the grant is then met by the 403 step-up on the retry, as in the TypeScript SDK). A cold start with an access token the server no longer accepts costs one 401 round trip before the refresh, unless the application restores both the expiry and the AS metadata itself. Against 2025-03-26-era servers that publish no metadata at all, in-process expiry now also goes through that 401 (and the failing well-known probes) instead of a single pre-request refresh; everywhere else in-process behaviour is unchanged. Types of changes Bug fix (non-breaking change which fixes an issue) New feature (non-breaking change which adds functionality) Breaking change (fix or feature that would cause existing functionality to change) Documentation update Checklist I have read the MCP Documentation My code follows the repository's style guidelines New and existing tests pass locally I have added appropriate error handling I have added or updated documentation as needed Additional context An earlier revision of this branch also folded in the #3256 recovery (expired DCR secret / invalid_client → re-register once) and a cold-start pre-request discovery mode. Review surfaced enough edge cases in both (403 step-up path, pre-registered credentials, tokens outliving their registration, a coarse-clock test knob) that they're better handled separately, so this PR is cut back to the refresh fix and the rest follows: #3256 (lapsed client_secret_expires_at, invalid_client handling incl. the 403 step-up exchange) — separate PR. Stored-token contract: an SDK-stamped issuer (and client binding) plus issued_at on the persisted token, following the OAuthClientInformationFull.issuer precedent, and a way for TokenStorage to forget tokens. Known exposures until then, stated rather than fixed here: (a) for pre-registered / unstamped client_info the 401-path refresh presents the stored refresh token (and client secret, as the code exchange already did) to whichever issuer the resource server's PRM now names — needs a token issuer stamp to detect; (b) clear_tokens() is memory-only, so a process that re-registers but cannot complete authorization leaves the previous client's tokens.json beside the new client_info, and the next process presents that refresh token under the new client once (rejected as invalid_grant) before authorizing; (c) verbatim storages get no real expiry across restarts. Refresh-failure classification and the {server-origin} fallback base used when PRM named an AS whose metadata could not be fetched belong in the same pass. No conformance scenario issues a refresh token today (modelcontextprotocol/conformance#139 is the nearest), so this isn't observable there yet. Supersedes #2492, #2875, #3263. (#1784 and #3248 restore expiry in _initialize, which this PR deliberately doesn't; the stored-token follow-up covers that.) AI Disclaimer
Open Graph Description: On a 401, OAuthClientProvider now tries the stored refresh token (after rediscovery) before falling back to interactive authorization, and the pre-request refresh only runs once authorization-serve...
X Description: On a 401, OAuthClientProvider now tries the stored refresh token (after rediscovery) before falling back to interactive authorization, and the pre-request refresh only runs once authorization-serve...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/3328
X: @github
Domain: github.com
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /:user_id/:repository/pull/:id/files(.:format) |
| route-controller | pull_requests |
| route-action | files |
| fetch-nonce | v2:593342d2-0dc7-5178-758b-d62b0165c072 |
| current-catalog-service-hash | ae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b |
| request-id | B0EE:D5AA4:16836EF:1DFBBA9:6B013261 |
| html-safe-nonce | b47138d5fff8a8303e476e704ddc04488e7c28c8aacb82035877b18d2dd3ebdc |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCMEVFOkQ1QUE0OjE2ODM2RUY6MURGQkJBOTo2QjAxMzI2MSIsInZpc2l0b3JfaWQiOiIxNjgyMzg3MjE2MTc4OTUwNzUzIiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 4b1f7510d5c7f56d3bd8f7b76fbb41a27d2332f034d4f3bd6e753c91d0ab3985 |
| hovercard-subject-tag | pull_request:4300001549 |
| github-keyboard-shortcuts | repository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/modelcontextprotocol/python-sdk/pull/3328/files |
| twitter:image | https://avatars.githubusercontent.com/u/224885523?s=400&v=4 |
| twitter:card | summary_large_image |
| og:image | https://avatars.githubusercontent.com/u/224885523?s=400&v=4 |
| og:image:alt | On a 401, OAuthClientProvider now tries the stored refresh token (after rediscovery) before falling back to interactive authorization, and the pre-request refresh only runs once authorization-serve... |
| og:site_name | GitHub |
| og:type | object |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| diff-view | unified |
| go-import | github.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git |
| octolytics-dimension-user_id | 182288589 |
| octolytics-dimension-user_login | modelcontextprotocol |
| octolytics-dimension-repository_id | 862584018 |
| octolytics-dimension-repository_nwo | modelcontextprotocol/python-sdk |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 862584018 |
| octolytics-dimension-repository_network_root_nwo | modelcontextprotocol/python-sdk |
| turbo-body-classes | logged-out env-production page-responsive full-width |
| disable-turbo | true |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
Links:
Viewport: width=device-width