[Server] Add native OAuth 2.1 authorization server

[wachterjohannes]

Summary

The HTTP server transport already supports being an OAuth resource server (validating tokens) and an OAuth proxy to an upstream IdP. This adds the missing third piece: a self-contained OAuth 2.1 authorization server, so an MCP server can register clients, authorize users, and issue + validate its own RS256 JWT access tokens — without an external IdP or a third-party OAuth library (e.g. league/oauth2-server).

It is dependency-free apart from firebase/php-jwt, which the existing JwtTokenValidator already uses for validation; signing reuses it. No new hard dependency.

What's included (src/Server/Transport/Http/)

• Engine behind seams — AuthorizationCodeIssuerInterface / TokenGranterInterface with Native* implementations: authorization code grant with mandatory PKCE (S256), refresh-token rotation, one-time short-TTL codes, exact redirect_uri matching, constant-time client auth.
• Tokens & keys — JwtAccessTokenIssuer (RS256) producing tokens that validate unchanged through the existing JwtTokenValidator; RsaSigningKey, JwksMiddleware, and StaticJwksProvider for in-process self-validation (no network round-trip).
• Endpoints — AuthorizationEndpointMiddleware, TokenEndpointMiddleware, AuthorizationServerMetadataMiddleware (RFC 8414); DCR (RFC 7591) via StoredClientRegistrar + the existing ClientRegistrationMiddleware.
• Storage — ClientRepositoryInterface, AuthorizationCodeStoreInterface, RefreshTokenStoreInterface, optional AccessTokenStoreInterface, each with in-memory and PSR-16 implementations.
• Host seams — ResourceOwnerResolverInterface (the SDK can't authenticate users) and ConsentInterface (+ default AutoApproveConsent).
• OAuthException for RFC 6749 §5.2 error responses.
• A runnable example at examples/server/oauth-authorization-server/.

The engine is transport-agnostic (the middlewares are thin PSR-7 shells over it), so it can be driven directly from a framework controller too.

Tests

144 new unit tests (PKCE RFC 7636 vector, self-issued round-trip through JwtTokenValidator, granter behaviours, registrar, metadata, middlewares). phpstan level 6 clean.

Status

Draft. This is the SDK half of a larger effort to let Symfony MCP servers act as their own OAuth AS. Companion work, built on these primitives and validated end-to-end against a real Sulu MCP server:

• Tracking issue: [McpBundle] Support acting as an OAuth 2.1 authorization server symfony/ai#2134 — [McpBundle] Support acting as an OAuth 2.1 authorization server symfony/ai#2134
• MCP Bundle implementation (draft): [McpBundle] Add OAuth 2.1 authorization server support symfony/ai#2135 — [McpBundle] Add OAuth 2.1 authorization server support symfony/ai#2135

Feedback on the public API/seams welcome.

[soyuka]

I don't think we want to have anative oAuth server in this SDK it's way out of scope. We need to document this properly as it's easy added using an outside oAuth2 library component. IMO this subject is just like the JSON Schema we should probably ship a default library and give extension points if needed to use other libraries.

[wachterjohannes]

Closing in favour of ADR 0001 (#382): the SDK is an OAuth Resource Server (+ delegation), not an authorization server. Agreed — issuing tokens/keys/consent shouldn't live here.

The authorization-server need it addressed will be pursued where the ADR points — league/oauth2-server behind the SDK's validator/proxy seams — packaged as a reusable, opt-in layer in symfony/mcp-bundle rather than each app re-wiring it (incl. the RFC 7591 DCR gap). Tracking: symfony/ai#2134.

Thanks @soyuka for the clear scope ruling.