The security.authentication.user_auth configuration adds end-user context to requests. It allows the MCP server to accept and forward user credentials to downstream services. This feature supports two modes:
  • Token mode—Forwards an opaque token string (default).
  • JWT mode—Accepts a structural JWT without signature verification by default.
The following table lists the properties available in security.authentication.user_auth:
Property Purpose
enabled Enables or disables user credential ingestion
mode Specifies the mode: token (opaque) or jwt (parsed claims only)
header Defines the incoming header name. The default value is Authorization.
prefix Adds a prefix when forwarding credentials. The default value is Bearer.
forward_downstream Forces forwarding even if otherwise suppressed
token_exchange.* Configures an external POST request to swap the token before forwarding

Token exchange flow

Token exchange provides an additional security layer by replacing the original user token with a new token obtained from an external endpoint. The token exchange works as follows:
  • When enabled, the user token is sent to an exchange endpoint using a POST request.
  • The response is parsed using a JSON path expression.
  • The new token is forwarded downstream using the same header and prefix configured in user_auth.
  • Failures abort the request without falling back to the original token for deterministic security.
Note: The token exchange configuration is nested under user_auth, not at the authentication level. The runtime automatically applies user_auth.header and user_auth.prefix settings to the exchanged token.

Authentication enablement levels

Authentication behavior is controlled by three distinct switches. These switches determine whether authentication middleware, scope gating, and discovery filtering are active.

The following table lists the enablement levels, their configuration paths, and their purpose:
Level Key path Scope Purpose Typical use
Global security.authentication.enabled Top-level Master gate that enables or disables all authentication features. When false, both service account and user authentication settings are ignored. Temporarily disable all authentication for debugging
Service account security.authentication.service_account.enabled Sub-section Enables server credential injection using JWT or JWKS. Provides stable scopes for tool gating and discovery filtering. Backend identity and consistent authorization context
User authentication security.authentication.user_auth.enabled Sub-section Accepts end-user credentials and optionally performs token exchange before forwarding downstream. Per-request user context and least-privilege exchange
The interaction rules define how the enablement levels interact with each other. The following points summarize the interaction rules:
  • Global must be set to true for either sub-section to take effect.
  • You can enable either sub-section independently. Combined mode forwards both credentials unless suppressed.
  • Scope gating and discovery filtering activate only when global is true and at least one enabled credential provides scopes.
  • Token exchange runs only when user authentication is enabled and token_exchange.enabled=true.