Add Keycloak OAuth Provider for Enterprise Authentication and local dev

[stephaneberle9]

Description

This PR implements native Keycloak OAuth support for FastMCP, enabling enterprise-grade authentication for organizations using Keycloak identity and access management infrastructure. The implementation provides a complete authentication provider that handles Keycloak User Realms with robust JWT token validation and Dynamic Client Registration (DCR) support. This contribution also significantly simplifies local development by providing a Docker-based Keycloak setup that allows developers to test OAuth flows instantly without external dependencies.

Contributors Checklist

• My change closes Add Keycloak OAuth Authentication Provider leveraging Dynamic Client Registration (DCR) #1918
• I have followed the repository's development workflow
• I have tested my changes manually and by adding relevant tests
• I have performed all required documentation updates

Review Checklist

• I have self-reviewed my changes
• My Pull Request is ready for review

[jlowin]

It feels like there's way too much going on in this PR. Did an LLM author this?

• The example should be a minimal server/client pair like all other auth providers. There should definitely not be a docker-compose file.
• keycloak.py seems to reimplement our oauthproxy AND oidcproxy while still claiming (in the linked issue) to natively support DCR? Ideally this would be a minor amount of configuration against one of FastMCP's establish auth classes.

[stephaneberle9]

It feels like there's way too much going on in this PR. Did an LLM author this?

I do use Claude Code, yes, but not "blindly". Means that I don't vibe-code my changes but meticulously review and iteratively adapt whatever it is suggesting. That said, I must admit that I'd missed to do that with the README.md of the new keycloak auth example which most probably has caused some degree of confusion. Sorry for that! I've fixed this as per 715aa92 now.

The example should be a minimal server/client pair like all other auth providers. There should definitely not be a docker-compose file.

Keycloak is a leading identity provider that has a big extra advantage: it can very easily be run locally using Docker or Docker Compose. Therefore, it is frequently used as a substitute for production IDPs to create fully self-contained local dev setups. The intent of this contribution is to enable both easy FastMCP auth support for productive Keycloak instances and use of Keycloak as IDP in local FastMCP dev setups.

That said, I fully understand that the presence of the Docker Compose configuration and scripts adds some extra complexity which compromises the idea of having simplistic examples. I therefore have reorganized the Keycloak example in the following way:

• All the Docker Compose stuff, the start script and an extra README.md file have been moved into the keycloak subfolder
• The example folder itself is now very similar to the other examples and basically only contains the server.py and client.py files
• The README.md file in this folder is also very compact now. It clearly indicates that there two options: running the example with an already existing Keycloak instance or creating a local Keycloak dev instance with Docker Compose. For the details regarding how to proceed in the second case the user is referred to more detailed instructions in the README.md located in the keycloak subfolder.

keycloak.py seems to reimplement our oauthproxy AND oidcproxy while still claiming (in the linked issue) to natively support DCR? Ideally this would be a minor amount of configuration against one of FastMCP's establish auth classes.

No, the KeycloakAuthProvider is clearly NOT a reimplementation of OAuthProxy/OIDCProxy. It's a fundamentally different architecture:

OAuthProxy/OIDCProxy: Full OAuth authorization server that translates between non-DCR IDPs and DCR-expecting clients
KeycloakAuthProvider: Lightweight metadata proxy that exposes Keycloak's native DCR with minimal request/response modifications

What the KeycloakAuthProvider does:

• Extends RemoteAuthProvider (NOT OAuthProvider)
• Does NOT implement the OAuth flow
• Does NOT store tokens, codes, or manage OAuth state
• Only proxies 3 HTTP endpoints for metadata/request modifications:
  • /.well-known/oauth-authorization-server - Metadata discovery
  • /register - DCR with scope injection
  • /authorize - Authorization with scope injection

Key proofs we're NOT reimplementing::

• KeycloakAuthProvider doesn't require any client ID or client secret at instantiation - because it doesn't need to authenticate with Keycloak on behalf of clients. In contrast, OAuthProxy/OIDCProxy require upstream_client_id and upstream_client_secret because they act as a full OAuth client to the upstream provider.
• KeycloakAuthProvider reuses OIDCConfiguration from oidc_proxy.py instead of reimplementing OIDC discovery - it's leveraging existing FastMCP infrastructure, not duplicating it.

The fact that the Keycloak auth provider proxies some HTTP requests does not mean it reimplements OAuth flow logic. This is exactly the "minor amount of configuration against one of FastMCP's established auth classes" - it's built on RemoteAuthProvider and adds only the minimal proxying required to bridge Keycloak's native DCR with MCP client expectations.

The Keycloak auth provider does include OIDC discovery because Keycloak supports it natively, and it would be unfortunate to force users to manually configure the authorization, token, and other endpoints individually instead. However, this has been achieved by reusing, not duplicating, existing logic from OIDCConfiguration.