All OAuth providers now return correct invalid_client error codes
instead of unauthorized_client for auth failures. Previously only
OAuthProxy had this fix; now OAuthProvider (and InMemoryOAuthProvider)
also benefit.
* Fix RFC 8414 path-aware authorization server metadata discovery
Override get_well_known_routes() in OAuthProvider to rewrite the
authorization server metadata route to be path-aware based on issuer_url,
matching how protected resource metadata already works.
Closes#2527
* Update readme
* Fix Azure provider to handle OIDC scopes correctly
OIDC scopes (openid, profile, email, offline_access) were being
incorrectly prefixed with identifier_uri, causing Azure to reject
authorization requests. This fix:
- Detects OIDC scopes and sends them unprefixed to Azure
- Filters OIDC scopes from token validation (Azure doesn't include
them in access token scp claims)
- Still advertises OIDC scopes to clients via valid_scopes
- Also handles dot-notation scopes (e.g., User.Read) correctly
Fixes#2451, #2420
* Fix dot-notation scopes to be prefixed (custom scopes can have dots)
* Improve Azure scope handling docs with clear examples
* Add Discord OAuth provider and corresponding tests
* Update DiscordProvider client_secret and required_scopes documentation
* Add Discord to authentication support list in README
* Fix Discord token verifier to match actual API response format
Discord's /api/oauth2/@me endpoint returns:
- "scopes" as a list, not "scope" as a space-separated string
- "expires" as ISO timestamp, not "expires_in" as seconds
- "user" data directly in the response (no need for extra API call)
* Simplify Discord token verifier
---------
Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
* Add consent_csp_policy parameter to OAuthProxy
Allows customization or disabling of CSP directives on the consent page.
Fixes#2476.
* Add consent_csp_policy to OIDCProxy and update docs
* Fix HTML injection vulnerability in CSP policy
HTML-escape the CSP policy value before inserting into meta tag to prevent HTML injection when CSP policies contain quotes.
* sk-provider updates - aud not enforce, scopes enforce if present
* updating env_prefix, adding debug logs
* updating docs
* ruff formatting
* not changing prefix for backward compatiblity
* backward compatibility changes
* give more preference to base_url than mcp_url if both passed
* updating docs
* refactor
* updating example server
* updating readme of example
* updating docs
* updating tests to reflect what should ideally go in the parameter
Set access_type=offline and prompt=consent by default to ensure
refresh tokens are returned by Google. Also expose extra_authorize_params
so users can customize authorization behavior.
OAuth consent tests were timing out on Windows due to SQLite database
locking when OAuthProxy instances used the default DiskStore without
explicit MemoryStore configuration. Added explicit client_storage=MemoryStore()
to three tests in TestConsentPageServerIcon.
Also restored parallel testing on Windows (--numprocesses auto) which
was previously disabled but is now safe with proper test isolation.
* Fix consent form action for subpath mounting
When a FastMCP server is mounted at a subpath (e.g., /api/v1), the consent
form used a hardcoded absolute path (/consent/submit) that didn't include
the mount prefix, causing 404 errors on submission.
Changed the form to use an empty action (action="") which submits to the
current URL, making it work correctly regardless of mount path. Also
consolidated the consent endpoints to handle both GET and POST at /consent.
Fixes#2380
* Update integration test to use /consent instead of /consent/submit
* Fix OAuth metadata endpoint URLs when base_url differs from issuer_url
OAuth operational endpoints (/authorize, /token) are mounted at base_url,
but metadata was incorrectly declaring them at issuer_url. This caused
clients following the documented mounting pattern to receive incorrect
endpoint URLs in /.well-known/oauth-authorization-server.
Fixes#2287
* Update auth.py
* Remove unnecessary assertion from OAuthProvider init
* Add info log when issuer_url differs from base_url
* Bump ty to >=0.0.1a25 with type fixes
Follow-up to #2295. Updates ty and fixes compatibility issues with alpha 25, including:
- Updated ignore comment syntax (possibly-unbound-attribute → possibly-missing-attribute)
- Fixed async generator type handling with anext()
- Fixed type narrowing for timeout parameters
- Converted base_url assignments to AnyHttpUrl after string manipulation
- Added CallToolResult to return type annotations
- Removed redundant type casts
- Fixed test form data to use strings instead of bytes
ty alpha 25 has limitations with isinstance() narrowing on unions (see pyproject.toml for details), requiring some targeted type ignores.
* Pin ty to ==0.0.1a25
Alpha releases can have breaking changes, so pin to the tested version.
* Add custom token verifier support to OIDCProxy
OIDCProxy now accepts an optional token_verifier parameter to support
non-JWT token formats like opaque tokens from providers such as Clerk.
When provided, the custom verifier is used instead of creating a default
JWTVerifier. Parameters that only apply to JWTVerifier creation (algorithm,
required_scopes) raise clear errors when specified alongside a custom
verifier. Parameters with other purposes (audience for OAuth flow,
timeout_seconds for config fetch) remain allowed.
The custom verifier's required_scopes are automatically loaded and
advertised through OAuth discovery endpoints.
* Document custom token verifier support in OIDC proxy
* Update docs for required scopes
* add scopes
* Fix Azure scope validation
Azure returns unprefixed scopes in JWT tokens but requires prefixed scopes in authorization requests. The previous implementation incorrectly validated tokens against prefixed scopes, causing "invalid_token" errors.
Simplified AzureProvider to use standard JWTVerifier with unprefixed scopes for validation. Scopes are only prefixed when building the Azure authorization URL via _build_upstream_authorize_url() override.
Closes#2263
* Checkpoint progress
* Checkpoint progress
* add derive b64 method
* PR clean-up
* refactor da proxy
* Updates to tests
* Make jwt_signing_key required for oauth proxy
* use typing_extensions and fix tests
* PR Cleanup
* also adjust integration tests
* Update docs, use client secret to derive jwt signing key
* You win some you lose some, gg claude
* check for both in derive
* update documentation / clean up
* Update http.mdx
---------
Co-authored-by: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
* Fix Azure scope mismatch causing MCP client validation errors
The AzureProvider was prefixing scopes during authorization but not in
token validation or Protected Resource Metadata, causing MCP clients to
reject tokens with "Server granted unauthorized scopes".
Changes:
- Prefix required_scopes once during __init__ and use consistently
- Pass prefixed scopes to JWTVerifier for token validation
- PRM now advertises prefixed scopes to MCP clients
- Remove unnecessary idempotent prefixing logic in authorize()
- Update comprehensive documentation explaining scope handling
- Update tests to reflect corrected behavior
Closes#2151
* Clarify that identifier_uri is optional in docstring
* Enhance OAuth Proxy error responses with branded HTML pages
OAuth Proxy authentication errors now show styled HTML error pages in browsers
instead of raw JSON, with content negotiation for API clients. Enhanced error
messages explain common causes (ephemeral storage, server restarts) and provide
clear remediation steps.
Changes:
- Created enhanced authorization handler that extends SDK's AuthorizationHandler
- Created enhanced auth middleware that extends SDK's RequireAuthMiddleware
- HTML error pages use server branding (icon, name) from FastMCP instance
- Added comprehensive troubleshooting section to OAuth Proxy docs
- Added FAQ entry linking to detailed troubleshooting
* Add comprehensive tests for enhanced OAuth error responses
Tests cover:
- HTML error pages for browser requests with server branding
- Enhanced JSON responses with registration endpoint hints
- Content negotiation between HTML and JSON
- Enhanced middleware error messages for invalid_token
- WWW-Authenticate header format consistency with SDK
* Update language for new storage defaults
* update docs
* Update tests for simplified error messages
* Clean up messages
* Add comprehensive keyring integration tests
Prevents OS keyring pollution during testing by adding a global mock in
conftest.py. Tests verify keyring behavior across platforms and fallback
scenarios without writing to the actual system keyring.
- Add global mock_keyring fixture to tests/conftest.py
- Add TestOAuthProxyKeyring class with 6 keyring-specific tests
- Remove try/except ImportError for keyring (now required dependency)
- Add keyring extra to py-key-value-aio dependency
- Clean up extraneous implementation comments in oauth_proxy.py
* Update OAuth keyring documentation
Update all OAuth-related documentation to reflect keyring-based key management:
- Add version badges to jwt_signing_key, token_encryption_key, and client_storage parameters
- Standardize "Default behavior (`None`):" formatting with backticks
- Ensure consistent messaging about development-only defaults across all docs
- Update oauth-proxy.mdx, oidc-proxy.mdx, http.mdx, storage-backends.mdx, and upgrade-guide.mdx
* Use anyio as testing backend
* Remove asyncio markers
* Update streamable http tests
* Replace all subprocess tests
* Replace anyio task groups with asyncio context managers in tests
- Convert run_server_async from anyio task group pattern to asyncio.create_task with async context manager
- Remove task_group fixture from conftest
- Update all test fixtures to use async with run_server_async pattern
- Remove TaskGroup imports from all test files
- Tests now work with pytest-asyncio instead of pytest-anyio
* Update test_github_provider_integration.py
* Implement icon support in fastmcp
* Fix icon feature tests
- Update snapshot for ResourceTemplate to include icons field
- Remove OAuth mounting tests (belong to PR #2119, not this feature)
* Update docs
* Customize consent screen
* Use server website link if available
* Anchor link shouldnt have trailing slash
* Remove 'a FastMCP server named' from consent page message
* Update docs
* Add issuer_url parameter to OAuth providers for mounting scenarios
* Add get_well_known_routes
* Update docs
* Improve docs and tests
* Trigger CI
* Fix conditional test execution for Windows
* Upgrade to MCP 1.17+ with RFC 9728 compliance
Updates FastMCP to require MCP 1.17+ and implements RFC 9728-compliant
OAuth protected resource metadata URL handling.
The key change is that .well-known/oauth-protected-resource endpoints
are now registered at path-aware locations. For example, if an MCP
server is mounted at /mcp, the metadata endpoint is now at
/.well-known/oauth-protected-resource/mcp instead of
/.well-known/oauth-protected-resource.
This ensures proper OAuth discovery for path-based resource servers
and aligns with the MCP SDK's implementation of RFC 9728 §3.1.
Changes include:
- Update minimum MCP version from 1.12.4 to 1.17.0
- Use build_resource_metadata_url() for RFC 9728 compliance
- Configure CI to test with latest package versions (--upgrade)
- Update tests for path-aware metadata URLs
- Add icons field to Tool model (introduced in MCP 1.17)
* Fix RemoteAuthProvider integration tests for RFC 9728
* Fix parameterized test for nested base URL paths
