Supporting OAuth with an Identity Broker (Token Exchange Flow)

[bgaidioz]

MXCP currently supports several OAuth 2.0 / OpenID Connect (OIDC) identity providers such as Keycloak, Google, Salesforce, and Jira.

To support authentication and delegated access through an OAuth broker, such as Keycloak configured to federate with external identity providers (e.g. Google), MXCP would need to implement support for OAuth 2.0 Token Exchange as defined in RFC 8693.

In this model, Keycloak acts as an OAuth broker and token exchange service, capable of issuing both:

• Access tokens for its own protected resources (e.g. MXCP’s APIs), and
• Delegated tokens for downstream resource servers (e.g. Google APIs), by exchanging a Keycloak-issued access token for an external provider’s token.

Authentication Flow Overview

1. User Authentication (Keycloak as Identity Provider) The chat client interacts with MXCP. When an unauthenticated request is made, MXCP returns a 401 Unauthorized with an authentication challenge (e.g. /authenticate). MXCP initiates an OIDC Authorization Code flow with PKCE against Keycloak. After successful login, MXCP receives the Keycloak ID token, access token, and refresh token for the user.
2. MXCP Session Establishment MXCP issues its own MXCP access token, representing the authenticated session and carrying MXCP-specific authorization context (e.g. tool scopes, roles, permissions). This token is used by the chat client for subsequent calls to MXCP APIs. The Keycloak tokens remain internal to MXCP. They are not exposed to the client.
3. Delegated Access via Token Exchange When a tool within MXCP (e.g. a "Google Calendar" tool) requires access to a Google API on behalf of the user, MXCP performs an OAuth 2.0 Token Exchange with Keycloak. Keycloak validates the subject token, performs the exchange, and returns a Google access token, which MXCP then uses to call the Google API.
4. User Consent and Broker Mediation If the user has not yet linked their Google account or consented to the requested scopes, Keycloak will trigger the standard Google OAuth consent flow once. After consent is granted, Keycloak stores the external refresh token and can silently issue Google tokens on subsequent exchanges.