[Proposal] Outbound OAuth2 Authentication for AI Gateway

[Thenujan-Nagaratnam]

Problem

Today, when the AI Gateway proxies a request to a backend LLM, the only supported outbound authentication mechanism is a static, pre-shared API key (upstream.auth.type: api-key). A growing number of LLM providers and enterprise-hosted backends — Azure OpenAI behind an Entra ID app registration, self-hosted models behind a corporate OAuth2 proxy, any backend fronted by a standard IdP — require a short-lived OAuth2 bearer token instead of a static key.

Solution

Extend the existing typed upstream.auth field (today: api-key only) with a second value, oauth2.

upstream:
  url: https://my-backend.example.com
  auth:
    type: oauth2
    oauth2GrantType: client_credentials   # or "password" — optional, defaults to client_credentials
    oauth2TokenEndpoint: https://idp.example.com/oauth2/token
    oauth2ClientId: <client id>
    oauth2ClientSecret: <client secret>
    oauth2Scope: <optional scope>

At registration time, gateway-controller validates the params and attaches a first-party oauth2 policy (compiled into the runtime image) to the route. At request time the policy:

1. Checks an in-process cache, then a shared Redis cache, then (only on a double miss) calls the token endpoint.
2. Presents clientId/clientSecret via HTTP Basic auth (client_secret_basic).
3. Injects Authorization: Bearer <token> and forwards the request.
4. On any failure (unreachable endpoint, invalid credentials, malformed response), returns a generic 502 Bad Gateway (matches the org's existing auth-failure conventions).

Grants supported

• client_credentials (RFC 6749 §4.4) — the default, standard machine-to-machine grant.
• password (RFC 6749 §4.3, Resource Owner Password Credentials)

grantType is a first-class, forward-compatible parameter specifically so further grants can be added later without a breaking schema change.

Token caching (Redis-backed, two-tier)

Tokens are cached in two tiers:

1. In-process — near-zero latency on the hot path.
2. Shared Redis — every gateway-runtime replica converges on the same token instead of each independently hitting the IdP, and a replica restart doesn't force a fresh fetch.

Redis is an optimization layered on top of the token endpoint, not a hard dependency — controlled by a failureMode system parameter:

• open (default): a Redis outage falls back to fetching directly from the IdP on every request. Auth still works; you just lose cross-replica sharing until Redis recovers.
• closed: a Redis error is treated as a token-acquisition failure (502).

Cache keys are scoped per API (<keyPrefix><apiId>), not per route/resource: oauth2 config lives on upstream.auth.

Redis connection settings (host, port, password, failureMode, timeouts, pool size) are gateway/operator-level system parameters resolved via config.policy_configurations.oauth2_v1.redis.* — not something an individual API publisher sets. This mirrors the existing advanced-ratelimit policy's own Redis configuration exactly.

Configuration Reference

User Parameters (API Definition)

Business configuration — including credential material — is set per-API in the API definition (under upstream.auth), the same as api-key's existing fields.

Parameter	Type	Required	Default	Description
grantType	string	No	client_credentials	client_credentials or password.
tokenEndpoint	string	Yes		URL of the OAuth2 token endpoint this policy calls to obtain an access token.
clientId	string	Yes		OAuth2 client ID used to authenticate to the token endpoint.
clientSecret	string	Yes		OAuth2 client secret paired with clientId.
username	string	Only when grantType is password		Resource owner username. Unused for client_credentials.
password	string	Only when grantType is password		Resource owner password, paired with username. Unused for client_credentials.
scope	string	No		Optional space-separated list of scopes requested from the token endpoint.

System Parameters (Gateway/Operator-Level)

Resolved once for the whole gateway via config.policy_configurations.oauth2_v1.redis.* — not set per API. Every field has a default, so omitting the whole redis block is always valid (falls back to localhost:6379, no auth).

Parameter	Type	Default	Description
redis.host	string	localhost	Redis host name or IP address.
redis.port	integer	6379	Redis server port.
redis.username	string	(none)	Optional Redis ACL username.
redis.password	string	(none)	Optional Redis authentication password.
redis.db	integer	0	Redis logical database index.
redis.keyPrefix	string	oauth2:token:v1:	Prefix applied to every cached-token key.
redis.failureMode	string	open	open or closed — see Token Caching above.
redis.connectionTimeout	string (Go duration)	5s	Redis dial timeout.
redis.readTimeout	string (Go duration)	3s	Redis read timeout.
redis.writeTimeout	string (Go duration)	3s	Redis write timeout.
redis.poolSize	integer	0 (go-redis default: 10 × GOMAXPROCS)	Connection pool size for the shared client.

Example: Azure OpenAI via an Entra ID App Registration

upstream:
  url: https://my-resource.openai.azure.com
  auth:
    type: oauth2
    oauth2TokenEndpoint: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
    oauth2ClientId: <app-registration-client-id>
    oauth2ClientSecret: <app-registration-client-secret>
    oauth2Scope: https://cognitiveservices.azure.com/.default

Example: Resource Owner Password Credentials (legacy IdP bridging)

upstream:
  auth:
    type: oauth2
    oauth2GrantType: password
    oauth2TokenEndpoint: https://legacy-idp.example.com/oauth2/token
    oauth2ClientId: gateway-llm-client
    oauth2ClientSecret: s3cr3t-value
    oauth2Username: service-account-user
    oauth2Password: s3cr3t-service-account-password

Example: Pointing the shared token cache at a specific Redis instance

Set once at the gateway level (not per-API) via config.toml or Helm values:

[policy_configurations.oauth2_v1.redis]
host = "redis.internal.example.com"
port = 6379
password = "..."
failure_mode = "open"

Error Responses

All error responses are JSON with Content-Type: application/json, and never leak the underlying cause.

Scenario	Status	Message
Token endpoint unreachable or returned an error (e.g. invalid_client, invalid_grant)	502	failed to authenticate request to upstream service
Token endpoint response missing an access token	502	failed to authenticate request to upstream service
Redis unreachable and redis.failureMode is closed	502	failed to authenticate request to upstream service
grantType set to an unimplemented value	Rejected at policy load (configuration error)	'grantType' must be one of "client_credentials", "password"
grantType: password set without username/password	Rejected at policy load (configuration error)	'username' parameter is required / 'password' parameter is required

Open Questions

1. Should clientAuthMethod come back as configurable? Do we have to support other methods as well likeclient_secret_post? If so, the hardcoded-Basic decision needs revisiting.
2. Should we add support to other grant types too?
3. Is the Resource Owner Password Credentials grant worth keeping given current OAuth2 guidance discourages it, or should it be removed?
4. Should the typed upstream.auth extension propagate to MCP proxies too?
5. Should other Redis-backed policies share one client/caching library instead of each rolling its own? There are now two independent implementations of the same shared-client-registry pattern (advanced-ratelimit, oauth2) with zero code reuse between them, purely because no shared package exists in sdk/core. Worth consolidating, or is per-policy independence intentional?

Testing

Fully testable without any dependency on a real IdP or real Redis in production mode:

• Unit tests use httptest.Server (token-endpoint stand-in) and miniredis (in-memory Redis).