MCP Client: Add token exchange (RFC 8693) sample

[shin1488]

Adds token exchange as a sample, per the discussion in #88.

What's included

• samples/sample-mcp-client-token-exchange — OAuth2TokenExchangeSyncHttpRequestCustomizer, a single-grant request customizer for MCP hosts that are OAuth2 resource servers (a service behind a gateway holding a validated user Jwt). It reads the user Authentication from the McpTransportContext — same as the authorization-code customizer — and uses it as the principal of the OAuth2AuthorizeRequest, so the incoming user token is sent as the subject_token and exchanged for a token minted for the MCP call.
• tokenExchangeAuthorizedClientManager(...) builds the OAuth2AuthorizedClientManager with a TokenExchangeOAuth2AuthorizedClientProvider, and sets subject_token_type explicitly to urn:ietf:params:oauth:token-type:access_token and resource to the MCP server's canonical URI on the token response client.
• Opt-in failOnMissingAuthentication(boolean). The default skips the Authorization header when no user Authentication is present, in line with the authorization-code customizer.
• A README covering the topology, the exchange on the wire, the subject token type, the resource parameter, Keycloak setup and initialization guidance.
• Unit tests, and an integration test in samples/integration-tests.

Design choices (per the questions in #88)

Scope. Ships as a sample rather than inside mcp-client-security, as requested.

Subject token type. Set explicitly on the response client via setParametersCustomizer, rather than re-wrapping the Jwt principal as an OAuth2AccessToken to steer the default subject-token resolver. Same request on the wire, but the intent lives in the request rather than in the shape of the principal. RFC 8693 §3 defines ...:access_token for an access token issued by the authorization server being called — which is what the host holds in this topology — while ...:jwt is defined for sending a JWT as an authorization grant to a different authorization server (RFC 7523). Spring Security derives the identifier from the Java type of the subject token (TokenExchangeGrantRequest maps a Jwt to ...:jwt and any other OAuth2Token to ...:access_token), so a resource server's Jwt would go out as ...:jwt. Spring Authorization Server accepts both, so this only surfaces against servers that hold the distinction, such as Keycloak.

Missing user context. Default is to skip the header; failOnMissingAuthentication(true) throws instead, for multi-tenant setups where a user-scoped request must never go out anonymously.

The resource parameter

The MCP authorization specification requires MCP clients to implement RFC 8707 resource indicators: the resource parameter MUST be included in token requests, MUST identify the MCP server the token is intended for, and MUST be sent regardless of whether the authorization server supports it. The sample now does, and the unit test asserts it on the wire alongside subject_token_type.

Sending it is the client's part. What happens to it is not:

Layer	Requirement	In this sample
MCP client	send resource naming the MCP server	done, asserted on the wire
Authorization server	reflect resource into aud	ResourceIdentifierAudienceTokenCustomizer does this for authorization_code, client_credentials and refresh_token, but not for token exchange — see below
MCP server	validate aud	validateAudienceClaim defaults to false, so the token is accepted on the shared issuer

The integration test still observes aud: token-exchange-client, and it will keep doing so. ResourceIdentifierAudienceTokenCustomizer reads the resource from OAuth2AuthorizationGrantAuthenticationToken.getAdditionalParameters(), but Spring Authorization Server's OAuth2TokenExchangeAuthenticationConverter explicitly excludes resource (and audience) from the additional parameters and routes them into OAuth2TokenExchangeAuthenticationToken.getResources() instead. The converters for the other grants exclude only their own parameters — grant_type, code, redirect_uri, client_id for authorization_code; grant_type and scope for client_credentials; grant_type, refresh_token and scope for refresh_token — so resource falls through into the additional parameters, which is why the customizer works there. Token exchange is the one grant where RFC 8693 makes resource a first-class, multi-valued parameter, so Spring Authorization Server excludes it by name and passes it as a typed value instead.

So the audience is not bound for token exchange, and that is a library-side gap rather than something the sample can set right. I will report it separately.

Why the resource is bound to the registration

AuthorizedClientServiceOAuth2AuthorizedClientManager loads and saves authorized clients through the OAuth2AuthorizedClientService, which keys them by (clientRegistrationId, principalName) — the resource is not part of that key. A registration shared across several MCP servers would therefore serve a token obtained for one server out of the store when calling another, once audience binding is enabled.

This is the model the library already assumes: McpClientRegistrationRepository resolves the resource of a token request from the registration id. That mapping is populated by dynamic client registration and by client ID metadata documents, though — registrations declared under spring.security.oauth2.client.registration, as a resource-server host does, are stored with a null resource identifier — so the manager takes the resource directly.

Tests

OAuth2TokenExchangeSyncHttpRequestCustomizerTests (9) — Bearer attachment, the user Authentication used as the authorize-request principal, header skipped on missing authentication, opt-in failOnMissingAuthentication, the null-authorized-client guard, the resource requirement, and the token request on the wire: given a Jwt subject token, the form body carries subject_token_type=urn:ietf:params:oauth:token-type:access_token and resource=<the MCP server>.

StreamableHttpTokenExchangeTests (samples/integration-tests) — a user token obtained through the authorization_code flow by one client is exchanged by a different client registered with the token-exchange grant; the greeter tool responds with the original user's identity ("Hello test-user"); the exchanged token differs from the subject token, with sub=test-user preserved and aud containing token-exchange-client. It runs against the Spring Authorization Server based test authorization server, which accepts both ...:access_token and ...:jwt — hence the wire assertion in the unit test.

Not included (follow-ups)

• The WebClient counterpart (McpOAuth2TokenExchangeExchangeFilterFunction).
• A Keycloak-based variant of the sample (relates to Add examples for connecting with Auth0 / Keycloak and adding it to an MCP client such as Claude Desktop #42). The sample already sends subject_token_type=urn:ietf:params:oauth:token-type:access_token, which is what Keycloak's standard token exchange requires, but it runs against sample-authorization-server; the Keycloak specifics (26.2 floor, standard.token.exchange.enabled, audience mappers) stay as README notes for now.

Verification

./mvnw spring-javaformat:apply
./mvnw clean install -DskipTests
./mvnw -pl samples/sample-mcp-client-token-exchange test
./mvnw -f samples/integration-tests/pom.xml test -Dtest=StreamableHttpTokenExchangeTests

[shin1488]

Reworked per the discussion in #88: token exchange now ships as a sample module instead of being integrated into mcp-client-security.

What's included

• samples/sample-mcp-client-token-exchange: the token-exchange request customizer for MCP hosts that are OAuth2 resource servers, with the subject-token resolver inlined via a factory method (sends ...:access_token, accepted by both Keycloak and Spring Authorization Server), unit tests, and a README covering the topology, Keycloak notes, and initialization guidance.
• An integration test in samples/integration-tests exercising the full flow against the test authorization server and the streamable-HTTP MCP server.

Verification

./mvnw spring-javaformat:apply
./mvnw clean install -DskipTests
./mvnw -pl samples/sample-mcp-client-token-exchange test
./mvnw -f samples/integration-tests/pom.xml test -Dtest=StreamableHttpTokenExchangeTests

• Sample unit tests: 7/7 pass (OAuth2TokenExchangeSyncHttpRequestCustomizerTests) — Bearer attachment, the user Authentication used as the authorize-request principal, header skipped on missing authentication, opt-in failOnMissingAuthentication, and the null-authorized-client guard.
• Integration test: 1/1 pass (StreamableHttpTokenExchangeTests) — a user token obtained through the authorization_code flow by one client is exchanged by a different client registered with the token-exchange grant; the greeter tool responds with the original user's identity ("Hello test-user"); the outgoing token differs from the subject token, with sub=test-user preserved and aud containing token-exchange-client. The subject token is carried as a Jwt principal, so the access-token-wrapping resolver is exercised as well.

[shin1488]

Two updates to the sample, both about how subject_token_type is set.

Mechanism. It is now set explicitly on the token response client, via RestClientTokenExchangeTokenResponseClient.setParametersCustomizer(...), instead of re-wrapping the Jwt principal as an OAuth2AccessToken to steer the default subject-token resolver. Same request on the wire, but the intent lives in the request rather than in the shape of the principal.

Framing. I had described ...:access_token as a Keycloak accommodation, which undersells it. RFC 8693 §3 defines that type for an access token issued by the authorization server being called — which is exactly what a resource-server host holds — while ...:jwt is defined for sending a JWT as an authorization grant to a different authorization server (RFC 7523). Spring Security derives the type from the Java type of the subject token, so a Jwt principal goes out as ...:jwt; Spring Authorization Server accepts both, so this only surfaces against servers that hold the distinction, such as Keycloak. The docs now say that.

Worth noting that RFC 8693 §1 names this topology directly: "An OAuth resource server, for example, might assume the role of the client during token exchange", and the first example in the spec walks through exactly that.

Integration test still passes.

[shin1488]

Two follow-ups, both about subject_token_type.

Test. The integration test runs against Spring Authorization Server, which accepts both
...:access_token and ...:jwt, so it would still pass if the setParametersCustomizer(...) line
were removed — the behaviour the previous commit added was unguarded. Added a unit test that asserts
the token request itself: given a Jwt subject token, the form body must carry
subject_token_type=urn:ietf:params:oauth:token-type:access_token. The token response client is now
built by a package-private factory method so it can be exercised against a MockRestServiceServer.

Docs. The README and javadoc said the subject token resolver derives subject_token_type. It
does not: the resolver only chooses which token to send, and the identifier comes from
TokenExchangeGrantRequest, which maps a Jwt to ...:jwt and any other OAuth2Token to
...:access_token. Corrected both.

Sample tests 8/8, integration test 1/1. I have also updated the PR description, which still described
the original draft.

[shin1488]

Two changes from a review pass on the audience side.

resource is now sent. The MCP authorization specification requires MCP clients to implement
RFC 8707: the resource parameter MUST be included in token requests, MUST identify the MCP server
the token is intended for, and MUST be sent regardless of whether the authorization server supports
it. The sample was not sending it. It now does on every exchange, asserted on the wire next to
subject_token_type. I also corrected the class javadoc, which claimed the exchanged token's audience is the MCP server — it is not. Binding it requires the authorization server to reflect resource into aud; sample-authorization-server does not do so for this grant. I will follow up on that separately.

The resource is bound to the ClientRegistration rather than resolved per request.
AuthorizedClientServiceOAuth2AuthorizedClientManager loads and saves authorized clients through
the OAuth2AuthorizedClientService, which keys them by (clientRegistrationId, principalName), and
the resource is not part of that key — so a registration shared across several MCP servers would
serve a token obtained for one out of the store when calling another, once audience binding is on.
That is the model the library already assumes: McpClientRegistrationRepository resolves the
resource of a token request from the registration id. That mapping is only populated by DCR,
though, and a resource-server host declares its registrations statically, so the manager takes the
resource directly.

Sending resource is the client's part; whether it reaches the token's aud, and whether aud is
checked, are authorization server and MCP server concerns. On that: the audience is not bound for
token exchange, and the sample cannot set that right on its own —
ResourceIdentifierAudienceTokenCustomizer reads resource from the grant's additional parameters,
and Spring Authorization Server's token exchange converter routes it into
OAuth2TokenExchangeAuthenticationToken.getResources() instead. Raised in #88.

[shin1488]

Updated the MCP authorization specification links from the 2025-06-18 revision to
2025-11-25, the current one in force. The #resource-parameter-implementation anchor and
the resource MUST clause are unchanged there, so nothing in the sample's reasoning shifts —
the citations just point at the revision the reader will land on.

Three references: two in the README, one in the customizer javadoc.