MCP Token Exchange rule

The MCP Token Exchange rule sits on an MCP Server asset. When a user calls an MCP tool, the rule takes the caller's inbound bearer token and exchanges it — via RFC 8693 OAuth 2.0 Token Exchange — for a tool-specific token issued by an identity provider (IdP). The exchanged token is injected into a configurable request header (default: X-SL-Exchanged-Token) that the downstream tool pipeline reads when calling the target service.

Use this rule when your MCP Server exposes tools that connect to different backends — such as Salesforce, Jira, or internal APIs — each requiring its own service-specific credential. Without token exchange, you would either forward the user's broad-scoped token to every downstream service (a security risk) or embed credential-swapping logic in each tool pipeline. This rule centralizes token management: when a user calls a tool, the rule automatically obtains a token scoped to that tool's target audience on the user's behalf.

Important: The rule adds the exchanged token in a new header and does not remove the original inbound Authorization header. The downstream tool pipeline receives both the original broad-scoped token and the narrowly-scoped exchanged token. The tool pipeline must be written to read the exchanged token header, not the original Authorization header.

Rule execution order

Place the MCP Token Exchange rule after the MCP OAuth2 JWT Validator rule in the policy chain. The JWT Validator must validate the inbound token before this rule acts on it. The rule only acts on tools/call requests; it is a no-op for other MCP methods.

Exchange modes

The rule supports two RFC 8693 exchange modes, selected via the Exchange Mode field:

Impersonation (default): The exchanged token represents the end user only. The downstream service sees the user as the caller; the gateway's identity is not recorded in the token. No actor token is required, and no additional IdP configuration is needed.
Delegation: The exchanged token includes an act claim identifying the gateway as the party acting on behalf of the user. Use this mode when downstream systems or auditors need to know that a gateway invoked the tool on the user's behalf. Delegation requires additional IdP configuration (an impersonator role and the IdP's impersonation feature enabled) and either a static actor token or a client authorized to use the client_credentials grant for automatic actor-token fetch.
Tip: Set Requested Token Type to JWT in Delegation mode if the downstream service needs to inspect the act claim. An opaque returned token does not carry the act claim.

Per-tool token routing

A single rule instance can serve multiple tools with different target tokens using Tool Mappings. Each mapping row defines a boolean match condition evaluated against the invoked tool name — bound as $toolName in the expression — and optional per-tool overrides for Token Endpoint, Audience, Scope, and Resource. Rows are evaluated in order; the first row whose condition evaluates to true wins, and its override values replace the global STS settings for that request.

Note: $toolName is available only in the Tool Match Condition expression. The Audience, Scope, and Resource override fields are evaluated statically and do not have access to $toolName.

Token caching

Exchanged tokens are cached to reduce repeated round-trips to the STS. The cache key incorporates the subject token, token endpoint, audience, scope, resource, exchange mode, and actor token, so distinct exchange configurations are cached separately. Configure the Time-To-Live in Seconds to balance freshness with performance.

Note: All expression-enabled fields accept expressions from the SnapLogic Expression Language.


Field/Field set	Description
When this rule should be applied	Boolean expression that determines when this rule applies to a request. Default value: true
STS Connection	Connection settings for the Security Token Service (STS) that performs the token exchange.
Token Endpoint	Required. The STS token endpoint URL to which the exchange request is sent. Example: https://auth.example.com/oauth/token
Client ID	Required. The OAuth 2.0 client identifier registered with the STS.
Client Secret	Required. The client secret corresponding to the Client ID. Masked in the UI.
Client Auth Method	How client credentials are sent to the STS: BASIC: Credentials are sent in the HTTP `Authorization` header as a Base64-encoded string. BODY: Credentials are sent as form parameters in the request body. Default value: BASIC
Exchange Parameters	RFC 8693 parameters that control the token exchange request.
Exchange Mode	The token exchange mode. See Exchange modes above. Impersonation: The exchanged token represents the end user only. Delegation: The exchanged token includes an `act` claim recording the gateway as the acting party. Default value: Impersonation
Subject Token Type	The RFC 8693 type URI of the inbound token passed as the `subject_token` in the exchange request. ACCESS_TOKEN (default): Use this for a standard OAuth 2.0 access token issued by the authorization server, including access tokens that happen to be JWT-encoded. This is the correct choice for most deployments. JWT: Use this only when the subject token is a JWT from a different issuer or an external assertion — not a standard access token issued by the same IdP. ID_TOKEN: Use this when the subject token is an OpenID Connect ID token. CAUTION: Select ACCESS_TOKEN even when the inbound token is JWT-encoded. The token type describes the token's role, not its wire format. Some STS implementations reject exchanges when the type is set to `JWT` for a standard access token. Default value: ACCESS_TOKEN
Requested Token Type	The RFC 8693 type URI of the token to be returned by the STS: ACCESS_TOKEN (default): The STS determines the format; the returned token may be opaque or JWT-encoded. JWT: Request a JWT explicitly. Required for Delegation mode when the downstream service must inspect the `act` claim. Default value: ACCESS_TOKEN
Audience	The intended audience(s) of the exchanged token. Accepts a single string or a list of strings; each value is sent as a separate `audience` parameter per RFC 8693. Example: https://api.salesforce.com
Scope	Space-delimited scopes to request for the exchanged token. Single string only. Example: read:contacts write:contacts
Resource	The URI of the target resource server for the exchanged token (`resource` parameter). Single value only. Example: https://api.internal.example.com
Tool Mappings	A table of per-tool overrides. Each row defines: Tool Match Condition: A boolean expression evaluated against the invoked tool name, available as `$toolName`. The first row whose condition evaluates to `true` wins. Use `true` to match all tools. Token Endpoint, Audience, Scope, Resource: Per-tool overrides that replace the global values when the condition matches. Any field left blank inherits the global value. Use Tool Mappings to route different tools to different target audiences or token endpoints from a single rule instance. Example: Tool Match Condition: `$toolName.startsWith('salesforce_')`
Output Injection	Settings that control how the exchanged token is delivered to the tool pipeline.
Target Header Name	Required. The HTTP request header into which the exchanged token is injected before the request is forwarded to the tool pipeline. Default value: X-SL-Exchanged-Token
Target Header Prefix	The prefix prepended to the token value in the target header. Set to empty to inject the raw token without a prefix. The downstream tool pipeline and the header name and prefix must match what the target service expects. CAUTION: If the tool pipeline constructs the authorization header itself from the raw token, set this field to empty to avoid a double prefix such as `Bearer Bearer <token>`. Default value: Bearer
Delegation Settings	Additional settings for Delegation exchange mode. These fields are visible only when Exchange Mode is set to Delegation.
Actor Token	A token identifying the gateway as the acting party in a delegation exchange. Masked. Can be supplied as a static value or via expression. If left blank, the rule automatically fetches an actor token using the `client_credentials` grant with the configured Client ID and Client Secret. Automatic fetch requires the configured client to be authorized for the `client_credentials` grant on the STS. If it is not, supply a static actor token (for example, a machine-user personal access token). Default value: N/A
Actor Token Type	The RFC 8693 type URI of the actor token. Default value: ACCESS_TOKEN
Actor Token Scope	Optional scopes requested when the rule fetches its own actor token via `client_credentials`. Only relevant when Actor Token is blank. Default value: N/A
Time-To-Live in Seconds	The duration in seconds for which exchanged tokens are cached. Caching reduces repeated STS round-trips for requests with the same subject token, endpoint, audience, scope, resource, exchange mode, and actor token. Default value: 300
Description	The purpose of the rule.

Limitations

Only operates on tools/call requests. The rule is a no-op for other MCP methods (tools/list, initialize).
Supports same-IdP token exchange only. The rule authenticates with a single set of client credentials to a single IdP. Per-tool Token Endpoint overrides allow routing different tools to different authorization servers within the same IdP (for example, separate Okta Authorization Servers per tool), but do not bridge entirely different identity providers. Cross-IdP federation must be handled in the tool pipeline.
Client authentication to the STS supports BASIC and BODY methods only. Private Key JWT (client_assertion) is not yet supported.
Automatic actor-token fetch (when Actor Token is blank in Delegation mode) requires the configured client to be authorized for the client_credentials grant. If it is not, supply a static actor token.
Scope and Resource are single-valued. Only Audience accepts multiple values.
The original inbound Authorization header is not removed. Both the original broad-scoped token and the exchanged narrow-scoped token are forwarded to the tool pipeline.

IdP considerations

This rule is IdP-agnostic, but IdP-side configuration differs between providers. The following compares two validated implementations.

Audience model

	Okta	Zitadel
Audience per Authorization Server	One audience per Authorization Server. Dynamic audience is not supported.	Dynamic audience on a single token endpoint via the `audience` request parameter.
Multi-tool configuration	Requires one Authorization Server per tool. Use per-tool Token Endpoint overrides in Tool Mappings to point each tool at its own Authorization Server.	A single token endpoint with per-tool Audience overrides in Tool Mappings is sufficient.

Delegation setup (Zitadel)

For Delegation mode with Zitadel, the following IdP-side configuration is required in addition to the standard token exchange setup:

Enable the instance-level Token Exchange feature flag.
Enable Security Settings > Allow Impersonation.
Grant the actor identity an impersonator role (ORG_END_USER_IMPERSONATOR for same-org or IAM_END_USER_IMPERSONATOR for cross-org).
Supply the actor token explicitly in the Actor Token field (for example, a machine-user personal access token), because the confidential web application used for exchange cannot use the client_credentials grant.