Title: Validate the authorization server metadata issuer on every discovery path by maxisbey · Pull Request #3398 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: Validate the authorization server metadata issuer on every discovery path by maxisbey · Pull Request #3398 · modelcontextprotocol/python-sdk
X Title: Validate the authorization server metadata issuer on every discovery path by maxisbey · Pull Request #3398 · modelcontextprotocol/python-sdk
Description: The OAuth client now decides which issuer it expects before it fetches any authorization server metadata, and checks what follows against that one value: the metadata's issuer (RFC 8414 section 3.3) on the legacy no-PRM path as well as the PRM path, the SEP-2352 binding of stored credentials, and the issuer recorded on a new registration. A 403 scope step-up goes through the same discovery when it holds no metadata yet, and the two machine-to-machine providers gain an optional issuer= so pre-provisioned credentials can be tied to their authorization server. Motivation and Context Expected issuer on the legacy path too. On the 2025-03-26 fallback (no protected resource metadata, authorization server metadata fetched from the resource server's origin) the document's issuer was not checked, and the credential binding was re-evaluated afterwards against whatever issuer the document named. RFC 8414 section 3.3 says such metadata must not be used, and the TypeScript client applies the check on every path. Discovery now computes the expected issuer once (the PRM-advertised server, else the resource server's origin written the way metadata issuers are), validates metadata against it unconditionally (a root issuer served with its trailing slash still names the origin), and evaluates the binding against it before the metadata is fetched, which also covers the case where no metadata is served at all and the default endpoints are used. The post-fetch special case goes away. When none of the resource metadata locations answers and one of them failed with a server error (or 429), the flow now stops instead of reading that as "no resource metadata", so a transient failure cannot send a client with a bound registration down the legacy path. Scope step-up reuses discovery. A 403 insufficient_scope re-authorized with whatever metadata was in memory, and with none after a restart, in which case it used the default /authorize and /token on the resource server's origin even for servers that publish metadata, and never consulted the binding. It now takes the 401 path: discover first when nothing is held (reading a resource_metadata hint from the challenge too), then re-authorize with the SEP-2350 union; metadata already discovered in the process is reused as before. A 403 that is not a scope challenge is returned to the caller instead of being retried unchanged, as IdentityAssertionOAuthProvider already does. issuer= on ClientCredentialsOAuthProvider and PrivateKeyJWTOAuthProvider. These providers carry a fixed client_id (and a secret, or a signed assertion) and used whichever authorization server discovery produced; nothing else in the flow can say which server issued those credentials. The optional keyword names it: when the resource advertises several servers the matching one is used, and the token request is only built from metadata for that issuer; otherwise the flow stops with OAuthFlowError and drops the metadata and token it was holding, so the next request starts discovery afresh rather than refreshing against them. Same model as IdentityAssertionOAuthProvider; omitting it keeps today's behaviour. How Has This Been Tested? New and updated tests in tests/client/test_auth.py and tests/client/auth/extensions/test_client_credentials.py: legacy metadata naming another issuer is refused; a server_url with an upper-case host or explicit port, and a root issuer served with a trailing slash, still match the origin; a registration bound elsewhere is dropped before the metadata request and also when no metadata is served, from a 401 or a 403 challenge; a 5xx/429 on the resource metadata request stops the flow with stored credentials intact; the root-slash tolerance and its limit; a step-up after a restart discovers first and targets the advertised server; a non-challenge 403 ends the flow; issuer= on both providers (matching metadata with either root spelling, other issuer, no metadata, the configured server listed second, a non-URL value, and that a refusal leaves nothing behind to refresh with). Each new flow test fails against main's src/. I also drove the provider through httpx2.AsyncClient(auth=...) and streamable_http_client against local test servers (PRM and legacy paths, with and without metadata, 401-first and 403-first, client-credentials with and without issuer=). Full suite, coverage, strict-no-cover, pyright and ruff pass locally. Breaking Changes No API removals or signature changes; the new keyword is optional and last, and mcp.client.auth.utils gains issuers_match. These are fixes that bring the client in line with specified behaviour; the observable differences: A legacy (no-PRM) server whose authorization server metadata names an issuer other than its own origin now gets OAuthFlowError: Authorization server metadata issuer mismatch. As on the PRM path since 2.0 there is no client-side override (the TypeScript client has one; adding it here would be a separate decision). On that path, stored credentials recorded against a different issuer are discarded before the metadata request rather than after it, and also when no metadata is served. When no protected resource metadata location answers and one of them returned a 5xx or 429, the flow raises OAuthFlowError instead of moving on to the legacy path. credentials_match_issuer treats https://host and https://host/ as the same issuer, so a record stamped in either form keeps matching on both paths. A scope step-up performs discovery first when no metadata is held in the process; a 403 without insufficient_scope is no longer retried. 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 am assigned to the linked issue (or it is labeled help wanted, or I'm a maintainer) I have disclosed any AI assistance and can explain the change in my own words 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 Two commits: the discovery change (expected issuer, binding before the fetch, step-up), then the issuer= keyword. The discovery block in async_auth_flow is re-indented under one new condition, so the whitespace-insensitive view is the easier read there. Two things are unchanged from main and left for a separate change: how discovery state is carried between passes (metadata held from an earlier pass while a later one selects a different server), and the fallback to the 2025-03-26 default endpoints when an advertised authorization server's metadata cannot be fetched. AI Disclaimer
Open Graph Description: The OAuth client now decides which issuer it expects before it fetches any authorization server metadata, and checks what follows against that one value: the metadata's issuer (RFC 8414 section...
X Description: The OAuth client now decides which issuer it expects before it fetches any authorization server metadata, and checks what follows against that one value: the metadata's issuer (RFC 8414 sec...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/3398
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:f9f43728-8ca8-ea89-c38d-f5de60ef264f |
| current-catalog-service-hash | ae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b |
| request-id | ABDE:24FC21:2D99F4:3BDFA1:6B00C26C |
| html-safe-nonce | c840135ca20a793276009e505b8b28737f6cd45d76f6dadd0bb7b55498cad3e8 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJBQkRFOjI0RkMyMToyRDk5RjQ6M0JERkExOjZCMDBDMjZDIiwidmlzaXRvcl9pZCI6IjU2MTIyMTQxNjk1NDI2NDAyMzYiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 9c77ee38084246b2813836155934007c71108af1ca3511b4b88f6fcc6b42ab66 |
| hovercard-subject-tag | pull_request:4368233735 |
| 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/3398/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 | The OAuth client now decides which issuer it expects before it fetches any authorization server metadata, and checks what follows against that one value: the metadata's issuer (RFC 8414 section... |
| og:site_name | GitHub |
| og:type | object |
| hostname | github.com |
| expected-hostname | github.com |
| None | 93edd3bebc4afb7ce711ee74cb5d2a95927850b082a4d43e212222389cb1c415 |
| 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 | 1fee81a280ea86312b69448e261b418189bfd5b5 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
Links:
Viewport: width=device-width