For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
About downstream-only login
Use the gateway’s OAuth issuer to enforce downstream IdP login on an MCP backend without per-user upstream OAuth.
Downstream-only login is a brokered authentication flow where the Solo Enterprise for agentgateway OAuth issuer authenticates the user against your downstream identity provider (IdP) and then forwards MCP traffic to the upstream MCP server. The user completes the login in a browser when the MCP client connects to the gateway. The issuer does not start a second OAuth flow with the upstream OAuth provider and does not rely on a per-backend elicitation Secret. The upstream MCP server either accepts unauthenticated calls or receives a static service credential that the gateway injects on every request through a backend policies.auth configuration.
Despite running on the same shared STS server that is enabled by the tokenExchange Helm feature, no upstream token is actually exchanged in this flow. The user’s IdP-issued JWT is validated at the gateway and then dropped before the upstream call. The upstream MCP server sees only the static service credential, if one is configured.
Downstream-only OAuth flow
The OAuth authorization server runs as a separate process on the controller pod, not in the data plane proxy. The proxy forwards requests on the /oauth-issuer/* path to the controller, which terminates the OAuth flow and federates with your downstream IdP. This setup is different from the proxy-mode MCP auth flow, where the data plane proxy handles the IdP’s endpoints at request time.
sequenceDiagram
participant Client as MCP Client
participant Proxy as agentgateway proxy<br/>(data plane)
participant CP as agentgateway controller<br/>(control plane / OAuth issuer)
participant IdP as Downstream IdP<br/>(Keycloak)
participant Server as Upstream MCP Server
Client->>Proxy: Connect to /mcp/<backend>
Proxy-->>Client: 401 + protected-resource metadata<br/>pointing to /oauth-issuer
Client->>Proxy: GET /oauth-issuer/authorize
Proxy->>CP: Forward /oauth-issuer/*
CP->>IdP: Redirect for downstream login
IdP-->>CP: Authorization code (via /callback/downstream)
CP->>IdP: Exchange auth code for ID token
IdP-->>CP: ID token + access token
CP-->>Client: Authorization code (controller-issued)
Client->>Proxy: POST /oauth-issuer/token (exchange code)
Proxy->>CP: Forward /oauth-issuer/*
CP-->>Client: Bearer JWT
Client->>Proxy: POST /mcp/<backend> with bearer JWT
Proxy->>Proxy: Validate JWT against IdP JWKS
Proxy->>Server: Forward request<br/>(inject static credential via policies.auth)
Server-->>Proxy: Response
Proxy-->>Client: Response
Comparison to other MCP auth modes
This downstream-only guide builds on the same token-exchange infrastructure as the chained brokered flow. The difference is what happens after the user finishes the downstream login.
Downstream-only vs. dual-OAuth
The agentgateway.dev/issuer-proxy key in mcp.authentication.resourceMetadata declares that the gateway’s OAuth issuer handles an MCP resource. When that resource has no upstream OAuth mapping, the issuer completes the flow after downstream login.
| OAuth flow | Flow | Description |
|---|---|---|
| Chained brokered flow | Downstream IdP login –> optional consent screen –> per-user OAuth flow with the upstream MCP server | The gateway stores the resulting upstream access token in the STS, keys it on the user’s identity, and replays it on every upstream call. Use this mode for MCP servers that require per-user credentials, such as GitHub, Slack, or Atlassian. |
| Downstream-only (this guide) | Downstream IdP login only | No consent screen, no upstream OAuth, and no per-backend elicitation Secret are required. The MCP client connects to the MCP server by using the credential that is defined in the backend’s policies.auth field. If no credentials are defined, unauthenticated requests are forwarded to the backend. Use this mode for MCP servers that need only corporate IdP gating, such as internal services, MCP servers that wrap a public API behind a static service token, or development environments. |
Downstream-only vs. proxy-mode MCP auth
The MCP auth guides describe a different OAuth integration where the gateway proxy itself acts as a thin MCP OAuth adapter at request time. In that mode, the downstream IdP is the authorization server from the MCP client’s perspective. The agentgateway proxy just makes the IdP’s endpoints discoverable in an MCP-compliant way and relies on the IdP’s dynamic client registration to register the MCP client on the fly.
In downstream-only login flows, the agentgateway controller runs a full OAuth authorization server at the /oauth-issuer/* endpoint. The MCP client treats the agentgateway proxy as its authorization server, and the controller federates with the downstream IdP behind the scenes against a single pre-registered client.
| Area of comparison | Proxy-mode (/mcp/auth/) | Downstream-only (this guide) |
|---|---|---|
| Authorization server seen by the MCP client | Downstream IdP, proxied by the gateway | Gateway controller’s /oauth-issuer endpoint |
| IdP must support dynamic client registration | Yes | No, a single pre-registered client is enough |
Requires the tokenExchange Helm feature to be enabled | No | Yes* |
| Can later layer on per-user upstream OAuth (dual-OAuth) | No | Yes, by configuring brokered elicitation with an upstream OAuth provider. |
* Note that although the downstream-only flow requires the tokenExchange setting to be enabled, no upstream token is actually exchanged. The name comes from the shared controller component (the STS server that is enabled by the tokenExchange Helm feature) that hosts the OAuth issuer for both downstream-only and dual-OAuth backends.
When to use downstream-only
Review common use cases for when to use downstream-only login flows.
- The upstream MCP server does not implement per-user OAuth, or the server’s authentication is satisfied by a single service credential that is shared across users.
- You want to gate MCP access on a corporate IdP login alone, without showing a consent screen or storing per-user upstream tokens.
- The MCP server runs inside your network and the gateway is the only public entry point. You want IdP login enforced at the edge, but the upstream MCP server itself does not need to know who the user is. The upstream trusts requests that come from the gateway, either by network reachability or because the gateway injects a static service token.
Use the chained brokered flow instead when the upstream MCP server requires its own OAuth flow per user and the gateway needs to store and replay each user’s upstream token.
Requirements
Complete Set up brokered elicitation to prepare the shared infrastructure:
- The
tokenExchangeHelm feature must be enabled on the controller so that the OAuth issuer runs on the controller pod. - The controller must have a
KGW_OAUTH_ISSUER_CONFIGvalue withdownstream_serverandgateway_config. Setincoming_clients.allowed_redirect_urisin the same value to restrict where the issuer can send an authorization code. See Redirect URI allowlist. Theconsentblock is not required and is ignored by downstream-only resources. - The gateway must route
/oauth-issuer/*to the controller’s issuer endpoint. Set this up once per gateway; the same route is shared with any dual-OAuth backends behind the same gateway.
Downstream-only does not require:
- A per-backend elicitation Secret or upstream OAuth mapping. The resource metadata declares the MCP resource, and the absence of an upstream OAuth mapping selects the downstream-only flow.
- A consent screen configuration. The consent screen is part of the dual-OAuth flow.
Redirect URI allowlist
The OAuth issuer sends an authorization code to the redirect_uri that the client names in its authorization request. The redirect URI allowlist binds the configured client ID to the URIs that you own, so that the issuer refuses every other destination.
Important
Setting the allowlist is what turns this binding on. When the list is empty or you omit it, the issuer accepts the configured client ID with any redirect_uri, so a crafted authorization request can deliver the authorization code to a destination that you do not own. The controller logs a warning at startup when the list is unset. Set the list for every deployment that configures a client ID.
The issuer applies the allowlist at each endpoint that accepts a client-supplied redirect URI.
/authorizeand/parcheck the requestedredirect_uribefore the downstream login starts. The issuer answers an unlisted URI with a400response and theinvalid_requesterror. The issuer returns that error to the caller, and never redirects to a URI that it cannot vouch for./registerchecks everyredirect_urisentry that a client sends. A client that registers an unlisted URI fails at registration with a400response and theinvalid_redirect_urierror.
A registering client often submits more redirect URIs than it redirects to, and one unlisted entry fails the whole registration. List every URI that the client registers, and not only the URI that it uses. The MCP Inspector is the common case: it registers both /oauth/callback and /oauth/callback/debug, so an allowlist that covers only the first rejects the Inspector at /register, before it starts an authorization request.
Review the following table to understand how the issuer matches an entry.
| Entry | How the issuer matches it |
|---|---|
An https URL, such as https://client.example.com/callback | The entry must include a host, and it must equal the requested redirect_uri character for character. |
An http URL on a loopback host, such as http://localhost:6274/oauth/callback | The issuer ignores the port, because a native client picks its port at run time. The scheme, host, path, and query string must still match exactly. A loopback host is localhost in any letter case, a four-part address in 127.0.0.0/8 such as 127.0.0.1, or an IPv6 loopback literal such as [::1] or [::ffff:127.0.0.1]. Shorthand such as 127.1 is not a valid address here, so the issuer rejects it. |
A private-use scheme URL, such as com.example.app:/oauth2redirect/example-provider | The entry must name a path or a host after the colon, such as com.example.app:oauth2redirect or vscode://solo.agentgateway/callback. The issuer rejects a scheme with nothing after the colon. The entry must equal the requested redirect_uri character for character. |
The issuer rejects an http URL on any other host, and it rejects any entry that includes a fragment. The issuer also checks the shape of every entry at startup, and refuses to start when an entry is empty or malformed.
The allowlist binds only the downstream client ID that you configure. For a client that identifies itself with a client ID metadata document (CIMD), the redirect_uris of that document apply instead, so a deployment that serves only CIMD clients needs no allowlist.
In Kubernetes mode, you set the allowlist in the incoming_clients.allowed_redirect_uris field of the KGW_OAUTH_ISSUER_CONFIG controller environment variable. Set up downstream-only login shows the field in a complete issuer configuration.