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

oauth2-proxy-injector

More documentation to follow.

I used Claude to teach me go. Claude scaffolded this project, but all the code was human-written.

See Claude.md and the deploy directory for an idea of how to configure.

The mutating webhook adds a sidecar running oauth2-proxy targeting the named port (the service must also target the port by name at this point) 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 in via configmap for non-sensitive values that are stable across services and via annotation for service-specific configurations.

Pod Annotations

Core Annotations

Port/Routing Annotations (Annotation-Only)

*Either protected-port or upstream must be set.

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):

TOCHECK:

Add paths for rewritten healthchecks