Skip to main content

Token exchange

The broker supports two distinct RFC 8693 flows on POST /oauth2/token:

FlowActivationResult
Third-party token exchangeStandard exchange parameters, including resourceA provider credential held in the encrypted token vault.
User impersonationOne audience equal to <impersonation.audience_prefix>/<canonical lower-case AgentID UUID or canonical_id> in local modeA locally issued broker token with an impersonated sub, target-derived UUID agent_id, and accountable act.iss/act.sub.

This page explains third-party token exchange. User impersonation does not resolve a third-party resource or return a provider credential. The target agent defines optional scope policy. The routing audience does not control issued aud. See user impersonation for its request, response, error, and audit contract. See Configuration for its operator configuration.

Third-party token exchange​

An agent that holds a third-party token has the problems that the broker prevents. The token can have broad access. You cannot revoke it for one agent. It does not give useful audit information. Token exchange keeps the provider credential in one controlled place. It returns access for a request:

  • The agent has only its broker-issued or upstream token. It never has a provider credential.
  • Each exchange uses an active delegation. Revoking a grant stops future exchanges.
  • Each exchange identifies a user, agent, and resource. This creates an audit record.

The broker implements this with RFC 8693 OAuth2 Token Exchange on its POST /oauth2/token endpoint.

The actors​

An exchange involves four parties. Each party has a specific role:

  • The privileged gateway exchanges the token for the agent. It authenticates to the broker with a signed client_assertion JWT. The broker validates this JWT against the upstream JWKS. Only a trusted gateway can request stored credentials. The assertion subject identifies the gateway in audit data.
  • The subject token is the agent token in subject_token. The broker uses CEL expressions to get the user and agent identities. The default claims are sub and azp. Together, they identify the delegation.
  • The resource is the target in resource. The broker normalizes it and compares it to third-party-service protected_resources. This identifies the provider token to return.
  • The broker makes sure that the user has an active grant for the agent and service. It retrieves and refreshes the stored third-party token. It then returns the token.

subject_token_type must be urn:ietf:params:oauth:token-type:access_token. This is the only accepted value.

How an exchange flows​

The response contains the third-party access_token, token_type, and issued_token_type. It also contains the granted_permission_sets used for the exchange. The caller can see the delegated access.

Two policy gates, composed as fail-closed AND​

An exchange has two independent policy gates. Both gates must allow the request:

  • Broker CEL — Can this exchange occur? The token endpoint evaluates a Common Expression Language policy with gateway assertion claims and RFC 8693 request fields. By default, the expression is true. You can restrict eligible gateways, agents, and resources.
  • ExtProc OPA — Can this proxied request continue? The ExtProc gateway sidecar can use an optional Open Policy Agent gate. It evaluates the proxied request and relevant MCP tool calls. It allows or denies the request. This gate is disabled by default.

The two gates form a fail-closed AND condition. ExtProc OPA can restrict a call that broker CEL allowed. Broker CEL can reject an exchange even when OPA allows the downstream call. Neither gate can grant access that the other rejected. A rejected exchange returns an error. The sidecar does not forward the original agent token.

Agent-subject boundary​

Local impersonation can issue a token for an agent acting for itself under an explicitly agent-permitting signed rule. The raw verified sub must exactly equal the audience-selected target UUID. Its reserved output sub and agent_id are equal, and act remains present; no category claim is added. No human delegation or grant/session creation is involved. Human subjects still require delegation. A signed exact-target subject on a human-only/omitted rule is ineligible even with same-text human delegation.

This does not introduce third-party agent identities. Third-party exchange evaluates token_exchange.claim_extraction.agent_subject_expression after validated principal extraction and security capture, before agent extraction, authorization or human grant/session/provider access. Its default is has(subject_token.sub) && has(subject_token.agent_id) && subject_token.sub == subject_token.agent_id. Matches return 403 access_denied, description agent-subject tokens cannot be exchanged for third-party service tokens, and no consent error_uri. This includes same-text human state and trusted external issuer tokens. Equal-claim legacy, mapped-principal and unsigned-subject human outputs are also rejected by default. Consent cannot recover these denials.

A configured expression fully replaces the default. Keep matching broker agent-subject tokens, for example by retaining the default as a disjunct. A non-matching override that references sub (a detector without subject_token.sub, such as false, fails startup) removes categorical rejection and protection against same-text human-credential access. Existing checks can then read human grants/sessions and return consent errors; exchange success is not promised. Detection errors/timeouts and dynamic non-boolean output instead fail closed with 500 server_error, no error_uri, and no human-state access. They never become false.

See the configuration reference, detector example and diagnostic reference.