oauth2-proxy¶
The implementation of Path A, adopted in ADR-010. The Istio Gateway (gateway-platform) delegates protected hosts under *.platform.yu-min3.com to oauth2-proxy via envoy_ext_authz_http; oauth2-proxy handles the entire OIDC redirect / cookie / refresh flow.
See ADR-010 for the full rationale and the comparison against Path B/C.
Components¶
| Item | Value | Notes |
|---|---|---|
| Chart | oauth2-proxy/oauth2-proxy 10.4.3 (appVersion 7.15.2) |
|
| Namespace | auth-system |
|
| Replicas | 2 | High availability while failOpen=false |
| nodeSelector | kubernetes.io/arch: amd64 |
Pinned to m4neo. The Pi 5 fleet isn't a good fit for load-balancing OIDC redirects |
| Provider | keycloak-oidc |
realm kensan |
| Cookie domain | .platform.yu-min3.com |
One session shared across every platform host (the core of SSO) |
Architecture¶
[browser]
↓ HTTPS
[Istio gateway-platform]
↓ ext_authz (HTTP)
[oauth2-proxy] ←→ [Keycloak realm "kensan"]
↓ allow (200) or deny (302 to login)
[Istio backend route]
- Registered as
envoy_ext_authz_httpvia Istio'smeshConfig.extensionProviders[oauth2-proxy](kubernetes/network/istio/istiod/values.yaml) - On successful auth, oauth2-proxy must return a plain 200 OK and stop there, so
upstreams = ["static://200"]is set. Istio's ext_authz only treats an HTTP 200 as "allow" (a 202 counts as deny)
Failure behavior¶
Because Istio is configured with failOpen: false, protected hosts (Hubble / Prometheus / Longhorn) return 503 if oauth2-proxy goes down. Grafana and Backstage bypass this entirely using app-native OIDC and are outside the CUSTOM ext_authz scope.
- Mitigated by 2 replicas + a PodDisruptionBudget (
minAvailable: 1) - Deliberately avoiding scheduling onto Pi 5 nodes: redirect / cookie validation benefits from AMD64 performance, and being exposed to the Pi 5 fleet's network instability (cilium-wifi-stability) would take down authentication for the whole platform
Scopes and claims¶
scope = "openid email profile". groups is a claim name, not a scope, and is deliberately excluded from scope (Keycloak rejects it with "Invalid scopes: groups").
The groups claim is auto-attached to the id_token by an oidc-group-membership-mapper on the istio-gateway-platform client, with id.token.claim=true.
CLI coexistence (skip_jwt_bearer_tokens)¶
Requests that already carry a Bearer token (e.g. an API call made after vault login -method=oidc or argocd login --sso) pass straight through via skip_jwt_bearer_tokens = true. This avoids layering an oauth2-proxy cookie session on top of an already-authenticated request.
extra_jwt_issuers = ["https://auth.platform.yu-min3.com/realms/kensan=istio-gateway-platform"] allowlists the issuer.
Chart gotchas (implementation notes)¶
- The chart prepends
image.registry(defaultquay.io) to the repository. Writingquay.io/...intoimage.repositorydouble-prefixes it. Justoauth2-proxy/oauth2-proxyis correct. - The chart's top-level
securityContext:maps to the container level (per the chart's values schema).fsGroupis pod-level only, so it needs to go underpodSecurityContext. - Passing
configFilecauses theemailDomainschart value to be ignored (configFiletakes precedence). Both need to be set.
Related¶
- ADR-010: discovering the absence of Istio-native OAuth2 and adopting Path A
- Gateway OIDC: the overall operations guide