0003 — Deprecate and remove the access-proxy chart¶

Status: Accepted; carried out in v1.32.0 (the chart is removed; the recipe for running upstream oauth2-proxy on another gateway lives in how-to/connect/oauth2-proxy.md) Date: 2026-09-25

Context¶

access-proxy wraps upstream oauth2-proxy as Envoy Gateway's external authorization backend, giving a console five things from a hostname and a backend name: login, a session that outlives a token, a forwarded bearer, global sign-out, and a posture (design/access-proxy.md#purpose). It was chosen over the gateway's own OIDC filter for four properties a bare token in a cookie cannot give: real session management, room for a large token, global logout, and background refresh (design/access-proxy.md).

Since then, Envoy Gateway's own OIDC filter — a SecurityPolicy's oidc block, naming a declared confidential client of the issuer — has matured enough to give a console with no authorization model of its own three of those four directly: it runs the code flow itself, keeps a session in its own cookie rather than a bare access token, forwards the resulting bearer to the backend, and refreshes in the background — all from configuration, with no chart of ours and no session store of ours. That is class A behaviour exactly as 0001 defines it: it refreshes against the issuer, so revocation reaches it at the next refresh, and ttl_cap bounds that window from the issuer's side — the same bound session.refresh gives from access-proxy's side today. The fourth property — global sign-out through a server-side session store — is real for access-proxy, but buys less than it appears to: oauth2-proxy encrypts each session with a key that lives only in the user's cookie, so nothing server-side, including a Back-Channel Logout receiver, can ever open a session it holds (back-channel-logout.md). The one advantage a server-side store would normally give — a sign-out that closes every window at once, server to server — is exactly the one this store cannot provide, on either shape of gateway OIDC.

What access-proxy costs to keep, per console: a Deployment, a share of a Valkey, a confidential client and its secret, and a cookie secret that must never be generated by a chart render an operator does not control (design/access-proxy.md). For a console with no authorization model of its own, that is infrastructure bought for a session-store property neither shape of gateway OIDC can actually make good on.

Decision¶

Two different doors, and this repository's own design pages have sometimes read as though they were one:

Gateway-native OIDC — the gateway's own filter (an Envoy Gateway SecurityPolicy's oidc block) runs the authorization-code flow in front of a console that has no authorization model of its own, as a declared confidential client of the issuer with requires as the admission gate, forwarding the bearer to the backend. This is the default replacement for access-proxy, for the exact case access-proxy exists to serve: a console that cannot run OpenID itself.
Native OIDC in the application — the console signs in as its own client, when it needs identity inside itself: per-user authorization from groups, per-user audit, tokens of its own to call something else (0001). This is a different door for a different kind of console, and it does not depend on this decision — it was already the right answer wherever it applied.

access-proxy is not deleted today. One documentation page survives, narrowed to the one case neither door above covers: a gateway that is not Envoy Gateway, fronting a console with no OpenID flow of its own, using oauth2-proxy with a declared confidential client the way the chart already wires it. It is removed inside the 1.x line (0007) once no such consumer remains — a component with zero consumers documented as a design decision is the appendix entry not-served.md#what-was-removed-and-why is for.

Consequences¶

A console moved from access-proxy to gateway-native OIDC does not gain Back-Channel Logout. The gateway's own filter has no BCL receiver either, for the same reason oauth2-proxy does not: nothing server-side holds a session the issuer's logout token could name. The console stays class A, bounded by its own refresh interval and by ttl_cap from the issuer's side, exactly as it was behind access-proxy (0001). What it does gain is real: no Deployment, no shared Valkey, and no cookie-secret handling to get right per console — the properties access-proxy needed infrastructure of ours for, gateway-native OIDC gives from configuration of the gateway alone.

Only a console that moves to native OIDC inside the application — the other door above — can take Back-Channel Logout, because only it can hold a session the issuer's POST has anything to name (back-channel-logout.md). Choosing between the two doors is therefore not only about where the authorization model lives (per 0001); it is also the only lever that decides whether a console can ever close the Back-Channel Logout window at all.

A console genuinely behind a gateway that is not Envoy Gateway never ran access-proxy at all — the chart is wired through Envoy Gateway's own SecurityPolicy external authorization, so it has nowhere else to attach. On such a gateway, run upstream oauth2-proxy yourself, with a declared confidential client row of this issuer, from the one documentation page that survives this decision — not from a chart of ours.

Alternatives considered¶

Keep access-proxy as the default and build Back-Channel Logout support into it anyway. Rejected: the constraint is upstream, in how oauth2-proxy encrypts a session, not in this chart's wiring around it — and the same constraint holds for the gateway's own filter, which is why gateway-native OIDC is a replacement for access-proxy rather than an upgrade past its limits. Nothing this repository could add to either reaches inside a browser-held key.

Replace oauth2-proxy with a proxy of our own that keeps sessions server-side and can be told to end one. Rejected for the same reason design/access-proxy.md#why-not-something-else gives for not writing the current proxy: identity-critical code on every console's request path, to recover a property that native OIDC inside the application already gives any console able to run it.

Corrected 2026-09-26¶

The Consequences section originally said a console behind a gateway that is not Envoy Gateway "keeps access-proxy". That was wrong: the chart is wired through Envoy Gateway's own SecurityPolicy external authorization and has never run anywhere else, so there was nothing to keep. The sentence now says what was always true — such a console runs upstream oauth2-proxy itself, with a declared confidential client row of this issuer, from the surviving documentation page, not from a chart of ours. This is a factual correction, not a reversal of the decision above.