ADR-010: Istio Native OAuth2 Provider Does Not Exist — Path Re-selection Required¶
Status¶
Decided: Path A — oauth2-proxy via envoy_ext_authz_http (2026-05-05).
This ADR supersedes the architectural premise of ADR-005, which assumed Istio 1.27 had a "native oauth2 extension provider". That premise turned out to be incorrect. The phased approach and two-stage authorization model in ADR-005 remain valid; only the implementation mechanism for Gateway-level OIDC was re-selected.
Decision rationale (after additional review on 2026-05-05)¶
Initial draft of this ADR also considered a "Path D" (per-service OIDC for OIDC-native apps + oauth2-proxy only for non-OIDC apps such as Hubble / Prometheus / Longhorn / Alertmanager). After comparing concrete SSO behavior, single-logout, audit centralization, and operational cost of adding new apps, Path A (unified oauth2-proxy fronting all platform UIs) wins on every axis except failure-mode resilience, which is mitigated by running oauth2-proxy with replicaCount: 2 + PodDisruptionBudget. Path D's "per-service OIDC for some apps" was rejected as middle-of-the-road complexity without a clear operational payoff.
CLI access paths (vault login -method=oidc, argocd login --sso) remain on per-service OIDC clients because they cannot route through oauth2-proxy. oauth2-proxy's --skip-jwt-bearer-tokens lets pre-authenticated Bearer tokens pass through unchanged, so CLI flows coexist with browser flows under Path A.
Path B (EnvoyFilter wrapping envoy.filters.http.oauth2) was rejected because the Envoy filter is officially "currently under active development" — not a stable surface for a homelab framed as an Enterprise Platform Engineering reference.
Path C (per-service OIDC for everything) was rejected because non-OIDC apps (Hubble / Prometheus / Longhorn / Alertmanager) have no native auth, leaving them either LAN-only or behind ad-hoc basic auth.
Date¶
2026-05-05
Context¶
ADR-005 (2026-05-03) decided to use "Istio's native oauth2 extension provider" to perform Gateway-level OIDC authentication, rejecting the OAuth2 Proxy approach from ADR-002 because:
"Istio 1.27 has shipped a stable Gateway API + native
oauth2extension provider. OIDC + JWT cookie handling can now be completed by Istio alone, without operating OAuth2 Proxy as a separate Pod."
Verification (2026-05-05)¶
While preparing the implementation, the proto definition of MeshConfig.ExtensionProvider was inspected directly from the Istio API repository:
curl -s https://raw.githubusercontent.com/istio/api/release-1.27/mesh/v1alpha1/config.proto \
| grep -E "Provider [a-z]+ = [0-9]+;"
The available oneof provider types in release-1.27 are:
| Field | Purpose |
|---|---|
envoy_ext_authz_http |
External authorization via HTTP service (e.g. oauth2-proxy) |
envoy_ext_authz_grpc |
External authorization via gRPC service |
zipkin / datadog / stackdriver / skywalking / opentelemetry |
Tracing |
prometheus |
Metrics |
envoy_file_access_log / envoy_http_als / envoy_tcp_als |
Access logging |
sds |
Secret Discovery Service |
There is no oauth2 / oidc / envoy_oauth2 provider type. The same is true for master, release-1.28, and release-1.26 branches.
The Istio reference docs (istio.io/latest/docs/reference/config/istio.mesh.v1alpha1/) confirm the same set.
What Was Likely Meant by "Native OAuth2"¶
There are two plausible features that were probably conflated:
-
Envoy's
envoy.filters.http.oauth2HTTP filter — exists in Envoy proper, can be inserted into Istio via theEnvoyFilterCRD. NOT aMeshConfig.ExtensionProvider. Currently flagged by Envoy docs as "currently under active development" and lacks OIDC discovery URL support (token/auth endpoints must be configured by hand). -
RequestAuthentication+AuthorizationPolicy— these are GA and stable, but they only do JWT verification and authorization. They cannot drive an OIDC redirect/cookie flow. A user without a JWT cannot be redirected to Keycloak by these resources alone.
Neither of these is a "drop-in" replacement for OAuth2 Proxy.
Requirements (unchanged from ADR-005 §Context)¶
- Minimize additional components
- Keycloak as the sole IdP for unified SSO
- Two-stage authorization: coarse at Gateway, fine in app
- Fail-secure: missing rules → no access by default
- JWT forwarding to apps (apps can read claims)
Paths Considered¶
Path A: oauth2-proxy via envoy_ext_authz_http (Recommended)¶
Place oauth2-proxy in auth-system namespace, register it as a MeshConfig.ExtensionProvider of type envoy_ext_authz_http, bind via AuthorizationPolicy with action: CUSTOM. oauth2-proxy handles the OIDC redirect, cookie, and refresh; Istio enforces the gate.
Pros
- The documented Istio pattern (Istio docs explicitly cover ext_authz with oauth2-proxy)
- oauth2-proxy is the K8s ecosystem standard (homelab references like khuedoan / ricsanfre / onedr0p use it widely)
- Native OIDC discovery URL support, mature refresh token handling, CSRF protection
- envoy_ext_authz_http is GA in Istio (stable proto)
- The "Enterprise Platform Engineering reference" framing benefits from a production-realistic pattern (AWS ALB + Cognito K8s analog)
Cons
- Adds one Pod in auth-system namespace (mitigated by replicas + PDB)
- Adds an oauth2-proxy Helm chart to operational scope
- Auth no longer "completes within Istio"; one extra hop (Gateway → ext_authz → Keycloak)
Path B: EnvoyFilter Wrapping envoy.filters.http.oauth2¶
Use Istio's EnvoyFilter escape hatch to inject Envoy's native oauth2 HTTP filter into the gateway-platform listener. Envoy handles the redirect/cookie directly.
Pros - No additional Pod; closer to ADR-005's "auth completes within Istio" intent - Refresh token + single logout supported in the Envoy filter
Cons
- The Envoy oauth2 filter is flagged "currently under active development" — not a stability guarantee suitable for production-aligned homelab
- No OIDC discovery URL support — authorization_endpoint and token_endpoint must be hardcoded (drift risk vs Keycloak)
- EnvoyFilter is Istio's brittlest API surface — known to break across Istio minor upgrades, especially when filter chain ordering changes
- CSRF protection requires a separate Envoy filter; HTTPS-only (acceptable for our case)
- Few production references; debugging requires Envoy-level expertise
Path C: Per-Service OIDC, Skip Gateway-level OIDC¶
Keep gateway-level Authorization at host/IP level (or none). Each service does its own OIDC: Argo CD, Grafana, Backstage, Vault all have native OIDC. Hubble/Prometheus/Longhorn UI guarded by NetworkPolicy + intra-LAN only or basic auth.
Pros - Zero implementation cost; effectively "stay at ADR-002 Phase 1" - Each service uses its native authz best - No extra components
Cons - SSO experience is fragmented (re-login per service) - No fail-secure default-deny at the edge - Services without OIDC support (Hubble / Prometheus / Longhorn UI) need ad-hoc protection - The "SSO handled entirely by Istio + Keycloak" homelab differentiator is lost
Decision¶
(Heading originally read "Decision (Pending)"; resolved as Decided: Path A on 2026-05-05 — see Status. The text below is preserved as written at decision time.)
Recommended: Path A. Rationale: - Path B's Envoy filter stability disclaimer ("under active development") is a real concern for any production-aligned setup, even a homelab - The "extra Pod" cost in Path A is one Helm chart and one namespace — small in absolute terms vs the differentiation Path A buys - Path C abandons the unified SSO story that ADR-002/005 explicitly chose - ADR-005's "no extra Pod" constraint was framed as a consequence (positive), not a requirement; the underlying requirement (unified SSO without per-service OIDC plumbing) is fully satisfied by Path A
Yu's decision is required before any of the path-specific YAML in this PR is bound to a live Gateway.
Implementation in This PR¶
After Path A was selected, this PR delivers the deploy-layer only:
bootstrap/keycloak/setup.shextended with a parameterized OIDC client function and an activeistio-gateway-platformclient whoseredirectUris=[https://oauth2-proxy.platform.yu-min3.com/oauth2/callback]. Vault KV population (secret/platform-auth/istio-gateway/platform) is bundled into the same script.meshConfig.extensionProvidersentry registering oauth2-proxy asenvoy_ext_authz_httpinkubernetes/network/istio/istiod/values.yaml.- oauth2-proxy Helm multi-source app under
kubernetes/auth/oauth2-proxy/(replicaCount 2 + PDB, ExternalSecret backed by the Vault KV path above). - ADR-010 (this file) status updated to Decided: Path A. ADR-005 marked Re-evaluation Required.
RequestAuthentication and the three-tier AuthorizationPolicy set (deny-all + ALLOW + CUSTOM) are intentionally deferred to follow-up PRs. Because no AuthZ policy binds the provider in this PR, runtime behavior is unchanged.
Addendum (2026-06-07)¶
Everything described above as "deferred to follow-up PRs" has since been implemented and bound:
requestauthentication-gateway-platform.yamlplus the AuthorizationPolicy set (authorizationpolicy-gateway-platform-{allow,oauth2}.yaml, and the gateway-prod counterparts) are live underkubernetes/network/istio/- The
meshConfig.extensionProvidersentry inkubernetes/network/istio/istiod/values.yamlis active (no longer a commented-out draft) - oauth2-proxy runs in
auth-systemwith replicaCount 2 + PDB as designed
One path detail differs from the Consequences section: the OIDC foundation YAML lives flat under
kubernetes/network/istio/ (no resources/ subdirectory was created).
Consequences¶
If Path A is chosen (recommended):
- One follow-up PR adds kubernetes/auth/oauth2-proxy/ Helm multi-source app
- Existing meshConfig.extensionProviders entry needs to be added (this PR includes a draft commented-out version in kubernetes/network/istio/istiod/values.yaml)
- The OIDC foundation YAML moves into a synced path (e.g., kubernetes/network/istio/resources/) and targetRef is bound to gateway-platform
- istio-gateway-platform Keycloak client gets redirectUris=[https://oauth2-proxy.platform.yu-min3.com/oauth2/callback] (or the chosen oauth2-proxy hostname)
If Path B is chosen:
- One follow-up PR adds an EnvoyFilter resource and the OIDC client redirectUris is [https://<each-host>.platform.yu-min3.com/oauth2/callback] per protected host
- meshConfig.extensionProviders is not used
If Path C is chosen: - This PR's foundation YAML is removed (or kept as documentation) - Per-service OIDC is configured separately for ArgoCD / Grafana / Backstage / Vault - Hubble / Prometheus / Longhorn UI gain ad-hoc protection (basic auth or LAN-only NetworkPolicy) - ADR-005 is marked Superseded by ADR-010, with this ADR documenting the actual decision
References¶
- ADR-002: Phased Implementation of Authentication and Authorization Architecture
- ADR-005: Phase 1 Authentication via Istio Native oauth2 + Keycloak (premise revision required)
- Istio API repo (release-1.27 branch):
mesh/v1alpha1/config.protoExtensionProvideroneof - Envoy docs: HTTP OAuth2 filter
- Istio docs: External Authorization task
- oauth2-proxy: official Istio integration guide