For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Token exchange
Exchange the token that a client sends to the gateway for a token that the backend accepts, at an OAuth authorization server, an identity provider, or the Solo security token service (STS).
Exchange the token that a client sends to the gateway for a token that the backend accepts, by calling an OAuth authorization server.
About
Instead of attaching a fixed credential to backend requests, the oauthTokenExchange backend authentication method exchanges the incoming token for a new, backend-specific token at an OAuth authorization server, then forwards that token to the backend. Token exchange is useful when a client authenticates to the gateway with one identity, but the backend requires a different, narrowly scoped token.
The gateway attaches the backend token itself, so the AI models and agents that call through it never see a backend credential. The user’s identity is preserved end-to-end, and the exchange can optionally carry an agent identity acting on behalf of the user (see actorToken), which keeps a consistent identity chain for auditing.
By default, the gateway reads the incoming token from the Authorization: Bearer header, exchanges it at the configured token endpoint, and attaches the returned token to the backend request in the Authorization: Bearer header.
Validation of the incoming token is the job of a route-level policy, such as JWT authentication, not the exchange itself. The exchange only reads the token and presents it to the authorization server.
The exchange makes one local check. If the incoming token is a JWT whose exp claim is in the past, the gateway returns a 401 and does not call the token endpoint. The check applies to both oauthTokenExchange grants and to crossAppAccess. It does not verify the signature and has no clock-skew leeway, so it also rejects tokens that JWT authentication still accepts during its 60-second leeway. Opaque tokens and tokens without a numeric exp claim go to the authorization server unchanged. The 401 carries WWW-Authenticate: Bearer error="invalid_token", error_description="The bearer token has expired". If MCP authentication also protects the route, the header adds resource_metadata with the protected resource metadata URL, so that MCP clients can refresh the token and retry.
Authorization servers that implement these grants include Keycloak, Microsoft Entra ID, Okta, Auth0, and ZITADEL.
Choose an exchange
Two backend authentication methods perform an exchange. Which one you need depends on how many authorization servers are involved.
| Method | Authorization servers | Use it when |
|---|---|---|
oauthTokenExchange | One | One server can issue the backend token from the incoming token. |
crossAppAccess | Two, across a trust boundary | The identity provider that authenticated the user and the authorization server that guards the resource are different parties. |
The oauthTokenExchange method supports two grants, and you choose between them with the grantType field.
| Grant | grantType | Standard | The incoming token is sent as |
|---|---|---|---|
| Token exchange (default) | TokenExchange | RFC 8693 | subject_token |
| JWT bearer | JwtBearer | RFC 7523 | assertion |
Some identity providers need provider-specific settings, or have vendor-specific variants of a grant. For example, the Google Cloud Security Token Service requires specific token types and scopes, and Microsoft Entra’s on-behalf-of flow is a variant of the JWT bearer grant. For provider-specific guides, see Identity providers.
Configuration
The token endpoint (authorization server) is configured as its own EnterpriseAgentgatewayBackend, which the EnterpriseAgentgatewayPolicy then references through backendRef. The gateway’s OAuth client secret is read from a Kubernetes Secret through clientAuth.secretRef. The policy attaches to the backend workload with targetRefs, so the exchange runs whenever the gateway forwards a request to that backend.
Review the following table to understand this configuration. For more information, see the API docs.
| Field | Description |
|---|---|
backendRef | Reference to the EnterpriseAgentgatewayBackend for the token endpoint. Mutually exclusive with url. Set exactly one of the two. |
url | The full address of the token endpoint, including the path. Use this field instead of backendRef to point at the authorization server directly, without creating an intermediate Kubernetes object. Mutually exclusive with backendRef. Do not set path when you use url. |
path | Path of the token endpoint on the backend. Must start with /. Defaults to /. |
grantType | TokenExchange (default, RFC 8693) or JwtBearer (RFC 7523). |
clientAuth | Client authentication for the token endpoint. method is ClientSecretBasic (default), ClientSecretPost, or PrivateKeyJwt. Use secretRef to read the client secret from a Kubernetes Secret. |
audiences, scopes, resources | The audience, scope, and resource parameters sent to the token endpoint. resources are RFC 8707 resource indicators. |
subjectToken.source | Where the gateway reads the incoming token from. Set exactly one of header, queryParameter, cookie, or expression, where expression is a CEL expression that reads the token from the request, such as a claim of a validated JWT. Defaults to the Authorization header with the Bearer prefix. |
subjectToken.tokenType | The type that the gateway reports for that token. Use a built-in name such as AccessToken (the default), Jwt, or IdToken, or a custom absolute URI. See Token types. |
actorToken | Optional RFC 8693 delegation actor token (TokenExchange grant only). Takes the same tokenType values as subjectToken. |
requestedTokenType | Optional token type to request, limited to AccessToken, Jwt, or IdToken, and valid only with the TokenExchange grant type. The response must return the type that you request. See Request a token type. |
location | Where to place the exchanged token in the backend request. Defaults to the Authorization header. |
additionalParams | Extra form parameters appended to the token request. Values are CEL expressions. |
cache | In-memory token cache. Defaults to 8192 entries. Set inMemory.maxEntries: 0 to disable. |
Validate the incoming token at the edge
The exchange sends the incoming token to the authorization server exactly as it arrived, and does not validate it first. Pair the exchange policy with a route-level traffic.jwtAuthentication policy so that an invalid or expired token is rejected at the gateway edge, before the gateway calls the token endpoint. The Standard token exchange guide walks through this, and the same policy applies to the JWT bearer grant.
Set preserveToken: true on that policy. By default the gateway removes the JWT after it validates it, so the exchange finds no subject_token and every request fails with a 400 and the message invalid request.
A SAML subject is the one case where edge validation does not apply, because a SAML assertion is not a JWT; see Cross App Access.
Choosing an identity provider
Solo Enterprise for agentgateway is identity-provider agnostic: grantType and the token endpoint backendRef are independent settings, so you can point either grant at any OAuth-family token endpoint. What varies is whether a given identity provider supports a given grant.
The standard, JWT bearer, and MCP guides in this section all use Keycloak as the token endpoint, because Keycloak brokers both grants: Standard Token Exchange (RFC 8693) and the JWT Authorization Grant (RFC 7523). The JWT bearer guide uses two Keycloak realms, where one realm issues the assertion and a second realm trusts that realm and mints the backend token. Cross App Access also uses Keycloak, standing in for both parties so the demo is self-contained.
Not every provider brokers a third-party token. Google’s own token exchange endpoint (sts.googleapis.com), for example, implements RFC 8693 only for Workload Identity Federation, so it returns Google-scoped tokens rather than brokering tokens from another issuer. For a walkthrough, see Google Cloud.
Some identity providers use their own variant of a grant, such as the Microsoft Entra ID on-behalf-of flow. For provider-specific guides, see Identity providers.
Note
To use a different authorization server, confirm that it supports the grant you need, then point the token endpoint backendRef at it.
Where the exchange runs
Token exchange runs in one of two places.
- In the proxy. For the standard token exchange, the JWT bearer grant, Cross App Access, and identity provider exchanges, the gateway proxy calls the token endpoint of an authorization server itself, such as Keycloak, Okta, Microsoft Entra ID, or a workload identity federation endpoint. You configure the exchange with a backend policy, such as
backend.auth.oauthTokenExchange, that targets the Service or EnterpriseAgentgatewayBackend that the gateway forwards to. This exchange does not use the STS, so you do not need to enable thetokenExchangeHelm settings. - In the Solo STS. For impersonation, delegation, and elicitation, the Solo Enterprise for agentgateway security token service (STS) mints or stores the token. The STS runs in the control plane, and you enable it with the
tokenExchangeHelm settings. The proxy calls the STS when a backend policy selects it, such asbackend.tokenExchangefor impersonation orbackend.entElicitationfor elicitation.
For more information, see About Solo STS token exchange.
Guides
A token that the gateway receives is often not a token that the backend accepts. Agentic environments commonly have two kinds of credential problems:
- Identity domain boundaries. The backend belongs to a different identity domain, such as GitHub or a Microsoft Entra ID tenant, and does not accept a token that your corporate identity provider (IdP) issued.
- Issuer and claim requirements. The backend is in your own identity domain, but it accepts tokens from one trusted issuer only, or it needs to know which agent acted on behalf of the user.
To choose a guide, start from the token that the backend must receive.
| Your goal | Option | Who issues the backend token |
|---|---|---|
| Exchange the incoming token for a backend token at an authorization server that you choose | Standard token exchange (RFC 8693) | The authorization server |
| Present the incoming token as an assertion to get a backend token | JWT bearer grant (RFC 7523) | The authorization server |
| Give an MCP server a backend-scoped token instead of the caller’s credential | Token exchange for MCP servers | The authorization server |
| Call an API in another organization as the signed-in user | Cross App Access (ID-JAG) | The resource authorization server |
| Call an API that accepts tokens from its own IdP only, such as Google Cloud or Microsoft Graph | Identity provider exchange | The external IdP |
| Make the backends that you own trust one issuer instead of every IdP | Solo STS impersonation | The Solo STS |
| Record which agent acted for which user | Solo STS delegation | The Solo STS |
| Use the user’s own credential for an upstream OAuth provider, such as GitHub | STS elicitation | The upstream OAuth provider. The Solo STS stores the credential. |