GitHub - spacemule/oauth2-proxy-injector: Mutating Admission Webhook to add oauth2-proxy as a sidecar to k8s pods

A Kubernetes mutating admission webhook that injects oauth2-proxy sidecars into pods for authentication.

I used Claude to teach me Go. Claude scaffolded this project, but as of 26 March 2026, some contributions (grunt work, mainly) are offloaded to Claude. All was reviewed, but I am a beginner. Don't use this for security critical purposes if you haven't reviewed it.

See CLAUDE.md and the deploy directory for configuration details.

Overview

The mutating webhook adds a sidecar running oauth2-proxy targeting the named port (the service must also target the port by name) in properly annotated pods. It adds easy authentication to services without having to edit existing helm-charts or manually add sidecars to manifests.

Configuration is done via:

• ConfigMap: Non-sensitive values shared across services in a namespace
• Annotations: Service-specific configurations and overrides

Value Sources

Most configuration values support three source types:

Example: Using fromEnv with env-secret

When you set an annotation to "fromEnv", the webhook skips generating that flag and instead creates an environment variable that reads from a Secret. You must also set env-secret to specify which Secret contains the values.

metadata:
  annotations:
    spacemule.net/oauth2-proxy.enabled: "true"
    spacemule.net/oauth2-proxy.env-secret: "oauth2-proxy-config"
    spacemule.net/oauth2-proxy.provider: "fromEnv"
    spacemule.net/oauth2-proxy.client-id: "fromEnv"
    spacemule.net/oauth2-proxy.oidc-issuer-url: "fromEnv"

The Secret should have keys matching the annotation names:

apiVersion: v1
kind: Secret
metadata:
  name: oauth2-proxy-config
type: Opaque
stringData:
  provider: "oidc"
  client-id: "my-client-id"
  oidc-issuer-url: "https://auth.example.com/realms/myrealm"

The webhook generates env vars like:

env:
- name: OAUTH2_PROXY_CLIENT_ID
  valueFrom:
    secretKeyRef:
      name: oauth2-proxy-config
      key: client-id

This is useful when:

• Secrets are managed via External Secrets Operator
• Configuration comes from a secrets management system
• You want to decouple config from annotations

Example: Using CSI Secrets Driver

For secrets via CSI (e.g., Vault CSI Provider, Azure Key Vault), use "file" for secrets and specify the SecretProviderClass:

metadata:
  annotations:
    spacemule.net/oauth2-proxy.enabled: "true"
    spacemule.net/oauth2-proxy.secret-provider-class: "vault-oauth2-secrets"
    spacemule.net/oauth2-proxy.client-secret: "file"
    spacemule.net/oauth2-proxy.cookie-secret: "file"
    # Other config can be literal or fromEnv
    spacemule.net/oauth2-proxy.client-id: "my-client"
    spacemule.net/oauth2-proxy.provider: "oidc"

The CSI volume is mounted at /etc/oauth2-proxy/conf.d/ and secrets are read via --client-secret-file and --cookie-secret-file flags.

Example: Using Vault Agent Injector

Vault Agent Injector writes files (not environment variables), so we need a different approach. The webhook supports two mechanisms:

1. env-file: Source a shell script containing export statements before starting oauth2-proxy
2. file:/path: Specify custom file paths for secrets with native --*-file support

Important: When using env-file, the oauth2-proxy image must include a shell (e.g., the Alpine-based images like quay.io/oauth2-proxy/oauth2-proxy:v7.6.0-alpine). The default distroless images will not work.

metadata:
  annotations:
    # Vault Agent Injector annotations (handled by Vault, not this webhook)
    vault.hashicorp.com/agent-inject: "true"
    vault.hashicorp.com/agent-inject-secret-env: "secret/data/oauth2"
    vault.hashicorp.com/agent-inject-template-env: |
      {{ with secret "secret/data/oauth2" }}
      export OAUTH2_PROXY_CLIENT_ID="{{ .Data.data.client_id }}"
      export OAUTH2_PROXY_OIDC_ISSUER_URL="{{ .Data.data.issuer_url }}"
      {{ end }}
    vault.hashicorp.com/agent-inject-secret-client-secret: "secret/data/oauth2"
    vault.hashicorp.com/agent-inject-template-client-secret: |
      {{ with secret "secret/data/oauth2" }}{{ .Data.data.client_secret }}{{ end }}
    vault.hashicorp.com/agent-inject-secret-cookie-secret: "secret/data/oauth2"
    vault.hashicorp.com/agent-inject-template-cookie-secret: |
      {{ with secret "secret/data/oauth2" }}{{ .Data.data.cookie_secret }}{{ end }}

    # This webhook's annotations
    spacemule.net/oauth2-proxy.enabled: "true"
    spacemule.net/oauth2-proxy.proxy-image: "quay.io/oauth2-proxy/oauth2-proxy:v7.6.0-alpine"

    # Source env file before starting (for non-secret config)
    spacemule.net/oauth2-proxy.env-file: "/vault/secrets/env"
    spacemule.net/oauth2-proxy.client-id: "fromEnv"
    spacemule.net/oauth2-proxy.oidc-issuer-url: "fromEnv"

    # Custom file paths for secrets (using file:/path syntax)
    spacemule.net/oauth2-proxy.client-secret-ref: "file:/vault/secrets/client-secret"
    spacemule.net/oauth2-proxy.cookie-secret-ref: "file:/vault/secrets/cookie-secret"

    # Literal values still work as before
    spacemule.net/oauth2-proxy.provider: "oidc"
    spacemule.net/oauth2-proxy.protected-port: "http"

When env-file is set, the container command becomes:

command: ["/bin/sh", "-c"]
args: ["source /vault/secrets/env && exec /bin/oauth2-proxy --provider=oidc ..."]

This sources the environment variables from the Vault-injected file, then starts oauth2-proxy with exec to ensure proper signal handling.

Fields That Don't Support fromEnv

Some fields are pod-specific and are used by the webhook at injection time, not by oauth2-proxy at runtime:

• protected-port - Which port to proxy
• upstream-tls - TLS mode for upstream connection
• ignore-paths - Paths to skip authentication
• api-paths - Paths requiring JWT only
• block-direct-access - Enable iptables protection
• ping-path / ready-path - Health check endpoints
• proxy-image - Container image to use
• pkce-enabled - Boolean abstraction (use code-challenge-method for fromEnv)

Pod Annotations

Core Annotations

Port/Routing Annotations (Annotation-Only)

*Either protected-port or upstream must be set.

Secret Provider Class Annotation

When set, a CSI volume is mounted at /etc/oauth2-proxy/conf.d/. Use "file" as the value for secret annotations to read from this mount.

Environment Secret Annotation

When env-secret is set, fields with "fromEnv" source will generate env var entries that read from this Secret. The Secret keys should match annotation names (e.g., client-id, provider, oidc-issuer-url).

When env-file is set, the container uses a shell wrapper to source the file before starting oauth2-proxy. This is useful for Vault Agent Injector which writes files containing export statements. Important: The oauth2-proxy image must include a shell (use Alpine-based images like v7.6.0-alpine).

The extra-env annotation allows injecting arbitrary environment variables from the same Secret. These env vars are available to oauth2-proxy at runtime and can be referenced in literal annotation values using ${VAR_NAME} syntax.

Example: Zitadel project ID for group-based access control

metadata:
  annotations:
    spacemule.net/oauth2-proxy.env-secret: "oauth2-config"
    spacemule.net/oauth2-proxy.extra-env: "project-id:PROJECT_ID"
    # Reference the env var in a literal annotation value
    spacemule.net/oauth2-proxy.allowed-groups: "${PROJECT_ID}:admin,${PROJECT_ID}:family"
    # Other config via fromEnv
    spacemule.net/oauth2-proxy.client-id: "fromEnv"
    spacemule.net/oauth2-proxy.oidc-issuer-url: "fromEnv"

Secret:

stringData:
  client-id: "123456789@my-project"
  oidc-issuer-url: "https://my-instance.zitadel.cloud"
  project-id: "123456789"  # Used by extra-env

This injects the PROJECT_ID env var into the oauth2-proxy container. The allowed-groups annotation generates --allowed-group=${PROJECT_ID}:admin --allowed-group=${PROJECT_ID}:family, and oauth2-proxy expands the env var at runtime to --allowed-group=123456789:admin --allowed-group=123456789:family.

Identity Override Annotations

Authorization Override Annotations

Cookie Override Annotations

Routing Override Annotations

Header Override Annotations

Behavior Override Annotations

Provider Override Annotations

Container Override Annotations

ConfigMap Keys

Blocking Direct Access with iptables

When using numbered port mode (service mode), the application container's ports remain accessible directly via the pod IP, potentially bypassing oauth2-proxy authentication. The block-direct-access annotation solves this by injecting an init container that configures iptables rules to block direct connections.

How It Works

1. An init container runs with NET_ADMIN capability
2. It creates iptables rules to:
   • Accept traffic from 127.0.0.1 (localhost) to the protected port
   • Drop all other traffic to the protected port
3. Health checks are automatically rewritten to route through oauth2-proxy
4. Only traffic through oauth2-proxy (on port 4180) can reach the protected port

Example

apiVersion: v1
kind: Pod
metadata:
  annotations:
    spacemule.net/oauth2-proxy.enabled: "true"
    spacemule.net/oauth2-proxy.protected-port: "8080"
    spacemule.net/oauth2-proxy.block-direct-access: "true"
    spacemule.net/oauth2-proxy.ignore-paths: "/health,/metrics"
spec:
  containers:
  - name: app
    image: myapp:latest
    ports:
    - containerPort: 8080
    livenessProbe:
      httpGet:
        port: 8080  # Automatically rewritten to port 4180
        path: /health

Requirements

• Cluster must allow pods with NET_ADMIN capability
• Pod Security Policies/Standards must permit this (if enforced)
• Health check paths should be added to ignore-paths to allow Kubelet access

Health Check Path Conflicts

If your application uses /ping or /ready paths (oauth2-proxy's defaults), you can customize oauth2-proxy's health check paths:

metadata:
  annotations:
    spacemule.net/oauth2-proxy.block-direct-access: "true"
    spacemule.net/oauth2-proxy.ping-path: "/oauth2/ping"
    spacemule.net/oauth2-proxy.ready-path: "/oauth2/ready"

Service Annotations

For Service mutation webhook (used with numbered port mode):

Full Example: CSI Secrets with Vault

apiVersion: v1
kind: Pod
metadata:
  annotations:
    # Enable injection
    spacemule.net/oauth2-proxy.enabled: "true"

    # Use Vault CSI driver for secrets
    spacemule.net/oauth2-proxy.secret-provider-class: "vault-oauth2"
    spacemule.net/oauth2-proxy.client-secret: "file"
    spacemule.net/oauth2-proxy.cookie-secret: "file"

    # Non-secret config via fromEnv (injected by Vault Agent)
    spacemule.net/oauth2-proxy.provider: "fromEnv"
    spacemule.net/oauth2-proxy.oidc-issuer-url: "fromEnv"
    spacemule.net/oauth2-proxy.client-id: "fromEnv"

    # Pod-specific settings (literal values)
    spacemule.net/oauth2-proxy.protected-port: "http"
    spacemule.net/oauth2-proxy.redirect-url: "https://myapp.example.com/oauth2/callback"
    spacemule.net/oauth2-proxy.ignore-paths: "/health,/metrics"
spec:
  containers:
  - name: app
    image: myapp:latest
    ports:
    - name: http
      containerPort: 8080