docs: proposal for OAuth 2.0 Token Exchange as Upstream Auth for MCP Backends

[nacx]

Description

This PR adds a proposal to implement OAuth 2.0 Token Exchange as Upstream Auth for MCP Backends. The proposal focuses on the APIs to enable token exchange for selected backends.

Related Issues/PRs (if applicable)

Proposal for #2036

Special notes for reviewers (if applicable)

N/A

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.49%. Comparing base (5d1305d) to head (0aba6dc).
⚠️ Report is 21 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2052      +/-   ##
==========================================
+ Coverage   84.38%   84.49%   +0.11%     
==========================================
  Files         130      133       +3     
  Lines       18112    18468     +356     
==========================================
+ Hits        15283    15605     +322     
- Misses       1883     1904      +21     
- Partials      946      959      +13     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Flgado]

Should we also support:

• private_key_jwt
• MTLS (maybe is tricky here)

I’m wondering whether all STS services support these authentication methods.

[nacx]

Yes, we could, although I think having an API with a type that can incrementally accommodate new methods is a good start. I'd start by providing one, and the API should be backwards-compatible when we want to add more.

[denniskniep]

Designing the ClientAuth in a generic way is a great idea.
I think the use case to authenticate via k8s service accounts jwt tokens could be quite common
see https://datatracker.ietf.org/doc/html/rfc7523#section-2.2
Then client_assertion_type & client_assertion is necessary, which optionally directly integrate with K8s ServiceToken Secrets/Mounts?

[nacx]

That sounds good as an addition once we have the basic implementation, but I'd rather keep the API open and backward-compatible and focus on one first use case. WDYT?

[denniskniep]

@nacx makes sense, thank you.

I thinks its also worth to forsee an token type agnostic exchange, so that you can theoretically get back an OAuth Transaction Token

[nacx]

Sounds good. IIUC, the current proposal should also cover that, as it allows for configuring the subject token type and requested token type. Is there something you see that's missing in this regard?

[Flgado]

Hmm, what will happen when tokens expired? Will need to reconnect for now ?
Should we not receive from the STS server the expires_in and try too get a new token before this ttl ?

[nacx]

Yes, we should probably use that returned value to configure the TTL in the cache, to min(expires_in, user_config)

[denniskniep]

The upstream AccessToken is cached with keyed by user token+ backend + scope

The upstream token is cached (keyed by user token + backend + scope) and set on the outgoing request.

If we replace the upstream AccessToken in the cache after refreshing it, then it is probably useless and that cache is never hit, because user tokens are AccessTokens with low validity windows.

[tabletenniser]

Is the cache in memory? Which means all of its content will be lost when we deploy / upgrade the gateway? I think it's fine, just want to call it out.

[nacx]

On an initial implementation, yes, although AIGW already has a persistent store (Redis) that is used for rate limiting. If we wanted to implement a persistent one, that could be done, although I don't think that persistence would be necessary for the exchanged tokens.

[Hritik003]

can you throw some light on which upstream providers support these?

[nacx]

What do you mean? Do you want a list of all existing IdPs that support OAuth token exchange?

[Hritik003]

this hard constraint is because token exchange requires a trusted “subject token” (user identity), but API key auth does not provide that?

[nacx]

Right, you need the incoming token to exchange for the upstream one.

[Hritik003]

Should this key be rotated because there can be a case where this key is compromised, and thus an attacker can impersonate the Gateway and request tokens of any user from the sts

[nacx]

That's a good point. The implementation could watch for changes to this PK and update the configuration if it changes.

[edan-binshtok]

hi @nacx and rest of the team

The proposal models a single token exchange. A lot of real-world federation against major clouds (GCP, AWS, Azure) needs two hops — would love to see chained exchange as a first-class concept before the API shape locks in. Also flagging two smaller papercuts at the bottom.

Thanks for driving this — the per-backend tokenExchange and the IdP/STS separation are exactly right.

The problem: single-hop is rarely enough

The first STS call validates the user's IdP-issued JWT and returns a federated token, but that federated token is usually not the credential the upstream backend actually wants. A second exchange/impersonation step is typically needed. Three concrete examples:

Keycloak → GCP

1. sts.googleapis.com/v1/token with the Keycloak JWT → federated access token (principal is principal://iam.../subject/<user>).
2. iamcredentials.googleapis.com/.../serviceAccounts/{sa}:generateAccessToken → normal SA access token.

Why hop 2: GCP IAM policies, audit pipelines, VPC-SC perimeters, and older client libraries are built around serviceAccount: principals. Federated principals force an N×M IAM-binding explosion (every user × every resource) instead of the standard "bind permissions to an SA, grant users tokenCreator on the SA" pattern.

OIDC IdP → AWS (cross-account)

1. sts:AssumeRoleWithWebIdentity with the OIDC JWT → temp creds for an entry role in account A.
2. sts:AssumeRole from account A into the target role in account B.

Why hop 2: AWS OIDC federation lands you in a single trust-account role. Cross-account access (the common org-wide-IdP + per-team-account topology) requires a second AssumeRole.

Entra ID On-Behalf-Of

1. Validate user's Entra-issued JWT.
2. OBO call to /oauth2/v2.0/token with requested_token_use=on_behalf_of to mint a token for the downstream API's audience.

Why hop 2: the user's token is audience-bound to the gateway's app registration; the downstream API rejects it.

(Same shape applies to Vault as a token broker: JWT auth → dynamic-credentials engine.)

In all cases, the proposal as written can express only the first hop.

Suggested API shape

A minimal change that unblocks all of these without breaking the existing single-hop config:

type MCPBackendTokenExchange struct {
      // ... all existing fields unchanged ...

      // Then optionally chains a follow-up exchange. The token returned by *this*
      // step is used as the subject_token for the Then step. The token injected
      // into the upstream request is the result of the final step in the chain.
      //
      // Use cases: GCP federated token → SA impersonation, AWS AssumeRoleWithWebIdentity
      // → cross-account AssumeRole, Entra OBO after initial validation.
      //
      // Chain depth SHOULD be capped (suggest: 3) to prevent runaway recursion.
      // +optional
      Then *MCPBackendTokenExchange `json:"then,omitempty"`

      // AdditionalParams adds vendor-specific parameters to the token exchange
      // request body (RFC-8693 §2.1 permits extension parameters). Standard
      // parameters (grant_type, subject_token, audience, scope, ...) MUST NOT
      // be overridden via this map.
      //
      // Examples: GCP STS uses a WIF provider URI as `audience`; AWS STS uses
      // `RoleArn`/`RoleSessionName`; Entra OBO uses `requested_token_use=on_behalf_of`.
      // +optional
      AdditionalParams map[string]string `json:"additionalParams,omitempty"`
}

Alternative if recursion is unappealing: replace Then with Steps []MCPBackendTokenExchangeStep on MCPBackendSecurityPolicy. Recursive is less invasive; a slice is easier to validate length on.

Worked example — Keycloak → GCP, end to end

backendRefs:
  - name: gcp-mcp
    securityPolicy:
      tokenExchange:
        # Step 1: Keycloak JWT → GCP federated token
        stsEndpoint: "https://sts.googleapis.com/v1/token"
        subjectTokenType: "urn:ietf:params:oauth:token-type:jwt"
        audience: "//iam.googleapis.com/projects/123/locations/global/workloadIdentityPools/keycloak/providers/keycloak"
        requestedTokenType: "urn:ietf:params:oauth:token-type:access_token"
        scopes: ["https://www.googleapis.com/auth/cloud-platform"]
        semantics: "Impersonation"   # GCP STS rejects actor_token

        then:
          # Step 2: federated token → impersonated SA token
          stsEndpoint: "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/user-mcp-sa@proj.iam.gserviceaccount.com:generateAccessToken"
          subjectTokenType: "urn:ietf:params:oauth:token-type:access_token"
          requestedTokenType: "urn:ietf:params:oauth:token-type:access_token"
          scopes: ["https://www.googleapis.com/auth/cloud-platform"]
          semantics: "Impersonation"
          additionalParams:
            lifetime: "3600s"

AWS cross-account version:

tokenExchange:
  stsEndpoint: "https://sts.amazonaws.com/?Action=AssumeRoleWithWebIdentity&Version=2011-06-15"
  subjectTokenType: "urn:ietf:params:oauth:token-type:jwt"
  semantics: "Impersonation"
  additionalParams:
    RoleArn: "arn:aws:iam::111111111111:role/keycloak-entry"
    RoleSessionName: "aigw-${user.sub}"
  then:
    stsEndpoint: "https://sts.amazonaws.com/?Action=AssumeRole&Version=2011-06-15"
    subjectTokenType: "urn:ietf:params:oauth:token-type:access_token"
    semantics: "Impersonation"
    additionalParams:
      RoleArn: "arn:aws:iam::222222222222:role/mcp-target"
      RoleSessionName: "aigw-${user.sub}"

The cache-key definition in §6.9 would need to become per-step (each step caches its own output keyed by its inputs) — worth one sentence in the doc.

Two smaller papercuts (independent of the above)

1. Drop the "actorToken required when Delegation" validation rule. GCP STS, AWS STS, and Entra OBO all reject actor_token. Forcing every Delegation config to fabricate one means those STSes can't use Delegation semantics at all — operators are pushed to Impersonation, losing the act claim and audit trail. Suggest letting actorToken be genuinely optional under Delegation (just no act claim if absent).

2. Soften the clientAuth "NOT RECOMMENDED" copy. Current doc treats omission as production-unsafe, but for GCP STS / AWS STS omission is the only correct configuration (those endpoints don't accept OAuth client auth — they authenticate via the subject token itself). Worth distinguishing the two cases so users targeting cloud STSes don't get told they're misconfigured.

---

Happy to put up a follow-up PR with the schema changes once the proposal lands, if this direction sounds reasonable. Thanks again!

[nacx]

The problem: single-hop is rarely enough

I'd like to focus first on having an implementation that supports the single hop, then add the possibility to chain them to enable the proposed use cases. It would be good to add an additional section to the proposal with the chained approach, or an additional document in the same directory, referring to a "v2" of this (that could be done by adding to this PR or in another independent one WDYT?).

Two smaller papercuts (independent of the above)

I've opened a base implementation for this spec here: #2092
There I've removed the "semantics" field, as it is redundant and can be derived from the presence of the actorToken bits, and made the actorToken fully optional.

[missBerg]

Approving this proposal. This is a proposal; refinements in approach may emerge during implementation.