Envoy and Istio Integration#

oauth2-proxy can act as an Envoy external authorization (ext_authz) service, delegating authentication decisions to oauth2-proxy via the /oauth2/auth endpoint. In Istio, this is wired through meshConfig.extensionProviders and an AuthorizationPolicy with action: CUSTOM. There is no dedicated Envoy/Istio integration guide in the official oauth2-proxy docs — the documented patterns focus on nginx auth_request and Traefik forwardAuth, but the ext_authz model is conceptually equivalent.

Header Propagation Options#

Three legacy flags control how oauth2-proxy propagates identity information in its auth response. All are defined in LegacyHeaders and convert to the InjectResponseHeaders / InjectRequestHeaders system at runtime 1.

--pass-authorization-header (pass_authorization_header) is a separate request-side flag that forwards the OIDC ID token to the upstream service as Authorization: Bearer, rather than in the auth response 6 7.

For advanced scenarios, all headers are fully configurable via the alpha YAML API under injectRequestHeaders and injectResponseHeaders, bypassing the legacy flags entirely 8.

Known Issue: Istio Filtering the Authorization Header#

Gateway-level header stripping#

Istio gateways can filter the Authorization header before it ever reaches oauth2-proxy. This prevents oauth2-proxy from reading the bearer token from incoming requests — the request arrives at oauth2-proxy with no Authorization header even though the client sent one. This is tracked in issue #2520, where a maintainer noted an in-progress workaround via PR #3262.

PR #3262 (feat: allow setting AuthorizationHeaderName, currently open) adds an AuthorizationHeaderName option so deployments can use a non-standard header name (e.g., Authorization-Custom) to carry tokens, bypassing the gateway's built-in filtering 9.

RequestAuthentication conflict with token refresh#

A more subtle problem arises in deployments that combine oauth2-proxy ext_authz with Istio RequestAuthentication 10:

1. oauth2-proxy session refresh is request-driven — it only triggers when a request arrives with a valid session cookie.
2. When oauth2-proxy successfully refreshes a session, it returns the new ID token via Authorization: Bearer <new_token> in the ext_authz response (requires set_authorization_header = true) 11.
3. However, Istio's RequestAuthentication validates the JWT on the incoming request, which still carries the original (now-expired) ID token. If JWT validation runs before or independently of ext_authz, the request is rejected with 401 before oauth2-proxy can refresh it.
4. Even when oauth2-proxy does return a refreshed token, if the Envoy ext_authz filter only allows a subset of response headers (e.g., only kubeflow-userid), the Authorization header is dropped and neither the upstream service nor RequestAuthentication sees the updated token.

Workarounds:

• Verify Istio filter chain ordering so ext_authz runs before RequestAuthentication JWT validation.
• Add Authorization to the ext_authz allowed response headers so Envoy propagates the refreshed token downstream.
• Consider removing RequestAuthentication for paths where oauth2-proxy is already the authentication authority — running both independently creates conflicts during token refresh.

Envoy original-path redirect loop#

When oauth2-proxy is deployed behind an Istio VirtualService with URI prefix rewriting, the post-authentication redirect can loop because oauth2-proxy only sees the rewritten (short) path, not the original one. Envoy injects the original path in X-Envoy-Original-Path. PR #2947 (open) adds --app-redirect-header / app_redirect_header to configure which request header oauth2-proxy should read for the redirect target 12.

Additional Notes#

• Real client IP: X-Envoy-External-Address is supported as a value for real_client_ip_header, allowing oauth2-proxy to correctly resolve the client IP when running behind Envoy (merged in PR #2755) 13.

• Group-based authorization via headers: A closed PR #1727 explored --allowed-groups-header to let a single oauth2-proxy instance enforce different group policies per Istio route.

• Header stripping: By default, oauth2-proxy strips incoming X-Forwarded-* and Authorization headers that it would set itself, preventing spoofing. This is controlled by skip-auth-strip-headers (default: true). In Istio deployments, verify this does not conflict with headers Envoy injects legitimately.

• Session store for Istio/Kubeflow: When multiple concurrent browser requests race to refresh the same session (common with Kubeflow notebooks behind Istio), Redis session storage is strongly recommended. Redis enables distributed locking that serializes refresh attempts and prevents duplicate refresh token use with rotation-enabled providers 10.

Key Source Files#