Skip to content
Latest (currently 2026.10.2) has the newest features, bug fixes, and CVE patches of Solo Enterprise for agentgateway.

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

Page as Markdown

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.

MethodAuthorization serversUse it when
oauthTokenExchangeOneOne server can issue the backend token from the incoming token.
crossAppAccessTwo, across a trust boundaryThe 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.

GrantgrantTypeStandardThe incoming token is sent as
Token exchange (default)TokenExchangeRFC 8693subject_token
JWT bearerJwtBearerRFC 7523assertion

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.

FieldDescription
backendRefReference to the EnterpriseAgentgatewayBackend for the token endpoint. Mutually exclusive with url. Set exactly one of the two.
urlThe 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.
pathPath of the token endpoint on the backend. Must start with /. Defaults to /.
grantTypeTokenExchange (default, RFC 8693) or JwtBearer (RFC 7523).
clientAuthClient 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, resourcesThe audience, scope, and resource parameters sent to the token endpoint. resources are RFC 8707 resource indicators.
subjectToken.sourceWhere 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.tokenTypeThe 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.
actorTokenOptional RFC 8693 delegation actor token (TokenExchange grant only). Takes the same tokenType values as subjectToken.
requestedTokenTypeOptional 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.
locationWhere to place the exchanged token in the backend request. Defaults to the Authorization header.
additionalParamsExtra form parameters appended to the token request. Values are CEL expressions.
cacheIn-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 the tokenExchange Helm 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 tokenExchange Helm settings. The proxy calls the STS when a backend policy selects it, such as backend.tokenExchange for impersonation or backend.entElicitation for 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 goalOptionWho issues the backend token
Exchange the incoming token for a backend token at an authorization server that you chooseStandard token exchange (RFC 8693)The authorization server
Present the incoming token as an assertion to get a backend tokenJWT bearer grant (RFC 7523)The authorization server
Give an MCP server a backend-scoped token instead of the caller’s credentialToken exchange for MCP serversThe authorization server
Call an API in another organization as the signed-in userCross 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 GraphIdentity provider exchangeThe external IdP
Make the backends that you own trust one issuer instead of every IdPSolo STS impersonationThe Solo STS
Record which agent acted for which userSolo STS delegationThe Solo STS
Use the user’s own credential for an upstream OAuth provider, such as GitHubSTS elicitationThe upstream OAuth provider. The Solo STS stores the credential.