OAuth2 Proxy

OAuth2 Proxy is a reverse proxy and authentication gateway for OAuth2 and OIDC providers. The HelmForge chart deploys the official upstream image with secure Kubernetes defaults and explicit proxy trust controls.

Key Features

• Official quay.io/oauth2-proxy/oauth2-proxy image pinned to v7.15.3
• Chart-managed Secret, existing Secret, or ExternalSecret credential modes
• Reverse proxy header trust disabled by default
• Config validation init container using --config-test
• Legacy config and alpha structured config support
• Ingress, Gateway API, dual-stack Service fields, ServiceMonitor, HPA, PDB, NetworkPolicy, and runtime tests

Security Scan

Framework	Score
MITRE + NSA + SOC2	95%

Security posture: acceptable.

Installation

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install oauth2-proxy helmforge/oauth2-proxy --namespace auth --create-namespace \
  --set auth.clientID=example \
  --set auth.clientSecret=example-secret \
  --set auth.cookieSecret=0123456789abcdef0123456789abcdef \
  --set config.provider=github \
  --set config.redirectUrl=https://auth.example.com/oauth2/callback

helm install oauth2-proxy oci://ghcr.io/helmforgedev/helm/oauth2-proxy --namespace auth --create-namespace

Examples

Existing Secret:

auth:
  existingSecret: oauth2-proxy-auth
  keys:
    clientID: client-id
    clientSecret: client-secret
    cookieSecret: cookie-secret

The default chart-managed credentials are local placeholders so disposable installs can pass runtime validation. Replace them with an existing Secret or ExternalSecret before any shared or production deployment, and keep the cookie secret stable across rollouts.

Trusted reverse proxy headers:

config:
  reverseProxy:
    enabled: true
    trustedProxyIps:
      - 10.42.0.0/16

Operations

Keep config.reverseProxy.enabled=false unless the deployment is behind a trusted ingress, gateway, or edge proxy. When enabled, define narrow trustedProxyIps CIDRs to avoid trusting client-supplied forwarded headers.

Architecture

OAuth2 Proxy usually sits between an ingress or Gateway and protected upstream applications. This chart can run it as a dedicated authentication endpoint, a reverse proxy, or a forward-auth style component depending on how your ingress controller or Gateway implementation is configured.

Typical flow:

1. The browser reaches /oauth2/start or a protected route.
2. OAuth2 Proxy redirects the user to the configured OAuth2/OIDC provider.
3. The provider sends the browser back to config.redirectUrl.
4. OAuth2 Proxy validates the response, sets a secure cookie, and forwards authenticated requests.
5. Metrics and health endpoints stay separate from application traffic.

Production Values

Use existing Secrets, secure cookies, explicit trusted proxy CIDRs, and at least two replicas:

replicaCount: 2

auth:
  createSecret: false
  existingSecret: oauth2-proxy-auth

config:
  provider: oidc
  oidcIssuerUrl: https://idp.example.com/realms/platform
  redirectUrl: https://auth.example.com/oauth2/callback
  cookie:
    secure: true
    domains:
      - .example.com
  reverseProxy:
    enabled: true
    trustedProxyIps:
      - 10.42.0.0/16

metrics:
  enabled: true
  serviceMonitor:
    enabled: true

networkPolicy:
  enabled: true
  extraEgress: []

The Secret referenced by auth.existingSecret should contain the client secret and cookie secret keys expected by the chart. Keep cookie secrets stable across rollouts or users will be logged out.

OIDC Routing

Ingress example:

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: auth.example.com
      paths:
        - path: /oauth2
          pathType: Prefix
  tls:
    - secretName: oauth2-proxy-tls
      hosts:
        - auth.example.com

Gateway API example:

gateway:
  enabled: true
  parentRefs:
    - name: public
      namespace: gateway-system
  hostnames:
    - auth.example.com
  path: /oauth2
  pathType: PathPrefix

Make sure config.redirectUrl exactly matches the externally reachable callback URL, including scheme, host, and path.

External Secrets

For GitOps, let External Secrets Operator manage the OAuth2 credentials:

auth:
  createSecret: false
  existingSecret: oauth2-proxy-auth

externalSecrets:
  enabled: true
  secretStoreRef:
    name: platform-secrets
    kind: ClusterSecretStore
  dataFrom:
    - extract:
        key: oauth2-proxy/auth

Use data when your secret backend stores each key separately, and dataFrom when a single remote object contains all required keys.

Alpha Config

Use alphaConfig.enabled=true when you need structured OAuth2 Proxy alpha configuration instead of command-line flags. Keep the generated config and classic config values aligned so the rendered arguments do not describe a different provider or cookie contract than the mounted config file.

Validation

After deployment:

helm test oauth2-proxy -n oauth2-proxy
kubectl get pods -n oauth2-proxy -l app.kubernetes.io/name=oauth2-proxy
kubectl logs -n oauth2-proxy deploy/oauth2-proxy --since=10m
kubectl get events -n oauth2-proxy --sort-by=.lastTimestamp

Validate a browser login flow as well as a direct health check. A healthy pod does not guarantee the OIDC provider, callback URL, cookie domain, and upstream proxy integration are correct.

Common Issues

Symptom	Likely Cause	Fix
Callback returns redirect_uri mismatch	config.redirectUrl differs from provider registration	Update either the chart value or the IdP client.
Users are logged out on every rollout	Cookie secret changes	Use auth.existingSecret or External Secrets.
Client IPs are spoofable	Reverse proxy trust is too broad	Keep trustedProxyIps narrow and platform-owned.
Login works but upstream denies user	Missing headers or email/domain allow-list	Check OAuth2 Proxy config and upstream expected headers.

Values

Parameter	Default	Description
replicaCount	2	Number of OAuth2 Proxy pods.
image.repository	quay.io/oauth2-proxy/oauth2-proxy	Official image repository.
auth.clientID	helmforge-local-client	Local placeholder OAuth client.
auth.clientSecret	helmforge-local-client-credential	Local placeholder OAuth secret.
auth.existingSecret	""	Existing credential Secret.
config.provider	github	OAuth2/OIDC provider.
config.reverseProxy.enabled	false	Trust reverse proxy headers.
alphaConfig.enabled	false	Render structured alpha config.
metrics.enabled	true	Enable metrics endpoint.
ingress.enabled	false	Render Ingress.
gateway.enabled	false	Render Gateway API HTTPRoute.
networkPolicy.extraEgress	[]	Append full custom egress rules.
externalSecrets.enabled	false	Render ExternalSecret resources.

Links

• OAuth2 Proxy
• OAuth2 Proxy GitHub
• Chart source