{"id":42072303,"url":"https://github.com/ianlintner/authproxy","last_synced_at":"2026-01-26T09:04:46.684Z","repository":{"id":326780384,"uuid":"1105444801","full_name":"ianlintner/authproxy","owner":"ianlintner","description":"OAuth2 Proxy Sidecar for Kubernetes Helmcharts and Configs","archived":false,"fork":false,"pushed_at":"2025-11-30T04:59:18.000Z","size":1972,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-02T05:35:50.133Z","etag":null,"topics":["github","helm","kubernetes","oauth2","oidc","security","sso"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ianlintner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-27T16:06:57.000Z","updated_at":"2025-11-30T05:02:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ianlintner/authproxy","commit_stats":null,"previous_names":["ianlintner/authproxy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ianlintner/authproxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianlintner%2Fauthproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianlintner%2Fauthproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianlintner%2Fauthproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianlintner%2Fauthproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ianlintner","download_url":"https://codeload.github.com/ianlintner/authproxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ianlintner%2Fauthproxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28771555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T08:38:24.014Z","status":"ssl_error","status_checked_at":"2026-01-26T08:38:22.080Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","helm","kubernetes","oauth2","oidc","security","sso"],"created_at":"2026-01-26T09:04:44.279Z","updated_at":"2026-01-26T09:04:46.678Z","avatar_url":"https://github.com/ianlintner.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OAuth2 Sidecar Proxy\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Kubernetes](https://img.shields.io/badge/Kubernetes-1.20+-326CE5.svg?logo=kubernetes\u0026logoColor=white)](https://kubernetes.io/)\n[![Istio](https://img.shields.io/badge/Istio-1.14+-466BB0.svg?logo=istio\u0026logoColor=white)](https://istio.io/)\n[![Helm](https://img.shields.io/badge/Helm-3.0+-0F1689.svg?logo=helm\u0026logoColor=white)](https://helm.sh/)\n[![Documentation](https://img.shields.io/badge/docs-MkDocs-blue.svg?logo=materialformkdocs)](https://ianlintner.github.io/authproxy/)\n[![GitHub](https://img.shields.io/github/stars/ianlintner/authproxy?style=social)](https://github.com/ianlintner/authproxy)\n\n\u003e Simple, secure OAuth2 authentication for Kubernetes applications using the **sidecar pattern**. \n\nEach application gets its own `oauth2-proxy` container that handles authentication transparently—no complex configuration needed.\n\n## ✨ Key Features\n\n- 🔒 **Secure by Default** - OAuth2/OIDC authentication with industry best practices\n- 🎯 **Sidecar Pattern** - Isolated authentication per application\n- 🚀 **Zero Application Changes** - Drop-in authentication for any HTTP service\n- 🌐 **Single Sign-On** - Share sessions across all `*.example.com` apps\n- 🎨 **Customizable UI** - Branded sign-in pages with Tailwind CSS\n- 📊 **Observable** - Prometheus metrics, health checks, audit logs\n- 🔄 **Multi-Provider** - GitHub, Google, Azure AD, Generic OIDC\n- 🛡️ **Security Hardened** - Non-root containers, read-only filesystems, minimal privileges\n\n## 📚 Documentation\n\n**📖 Full documentation: [https://ianlintner.github.io/authproxy/](https://ianlintner.github.io/authproxy/)**\n\n| Topic | Description |\n|-------|-------------|\n| [Quick Start](https://ianlintner.github.io/authproxy/getting-started/quickstart/) | Get running in 5 minutes |\n| [Architecture](https://ianlintner.github.io/authproxy/architecture/overview/) | How it works with diagrams |\n| [Installation](https://ianlintner.github.io/authproxy/getting-started/installation/) | Detailed setup guide |\n| [Adding Apps](https://ianlintner.github.io/authproxy/guide/adding-apps/) | Protect your applications |\n| [OAuth Providers](https://ianlintner.github.io/authproxy/providers/github/) | GitHub, Google, Azure AD |\n| [Configuration](https://ianlintner.github.io/authproxy/reference/configuration/) | All config options |\n| [Troubleshooting](https://ianlintner.github.io/authproxy/guide/troubleshooting/) | Common issues \u0026 solutions |\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Kubernetes 1.20+ with `kubectl` access\n- Istio 1.14+ service mesh installed\n- Helm 3 installed\n- Domain with DNS/TLS configured\n- OAuth app registered (e.g., GitHub OAuth App)\n\n### Install in 3 Steps\n\n#### 1. Create OAuth Application\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGitHub\u003c/b\u003e\u003c/summary\u003e\n\n1. Go to GitHub Settings → Developer settings → OAuth Apps\n2. Click **New OAuth App**\n3. Set **Homepage URL**: `https://example.com`\n4. Set **Authorization callback URL**: `https://auth.example.com/oauth2/callback`\n5. Save **Client ID** and generate a **Client Secret**\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGoogle\u003c/b\u003e\u003c/summary\u003e\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Create project → APIs \u0026 Services → Credentials\n3. Create **OAuth 2.0 Client ID** (Web application)\n4. Add **Authorized redirect URI**: `https://auth.example.com/oauth2/callback`\n5. Save **Client ID** and **Client Secret**\n\n\u003c/details\u003e\n\n#### 2. Install with Helm\n\n```bash\n# Clone the repository\ngit clone https://github.com/ianlintner/authproxy.git\ncd authproxy\n\n# Install the helm chart\nhelm install oauth2-sidecar ./helm/oauth2-sidecar \\\n  --set domain=example.com \\\n  --set cookieDomain=.example.com \\\n  --set oauth.provider=github \\\n  --set oauth.clientID=Ov23li1234567890abcd \\\n  --set oauth.clientSecret=1234567890abcdef1234567890abcdef12345678 \\\n  --set istio.gateway.existingGateway=your-gateway \\\n  --namespace default\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eOr create a values file\u003c/summary\u003e\n\n```yaml\n# values.yaml\ndomain: example.com\ncookieDomain: .example.com\n\noauth:\n  provider: github\n  clientID: Ov23li1234567890abcd\n  clientSecret: 1234567890abcdef1234567890abcdef12345678\n  \nistio:\n  gateway:\n    existingGateway: your-gateway\n```\n\n```bash\nhelm install oauth2-sidecar ./helm/oauth2-sidecar \\\n  -f values.yaml \\\n  --namespace default\n```\n\n\u003c/details\u003e\n\n#### 3. Deploy Example Application\n\n```bash\n# Deploy the example app\nkubectl apply -k k8s/apps/example-app/\n\n# Check deployment\nkubectl get pods -l app=example-app\n```\n\n#### 4. Test It Out\n\n```bash\n# Visit your app (will redirect to GitHub/Google login)\nopen https://example-app.example.com\n```\n\nYou should see:\n1. **Sign-in page** with your OAuth provider button\n2. **OAuth consent** screen (first time only)\n3. **Your application** - authenticated! 🎉\n\n## 🏗️ Architecture\n\n```\n┌─────────────┐\n│   Browser   │\n└──────┬──────┘\n       │ HTTPS\n       ▼\n┌─────────────────┐\n│  Istio Gateway  │\n│   (TLS Term)    │\n└───────┬─────────┘\n        │\n        ▼\n┌────────────────────────────────┐\n│     Kubernetes Service         │\n│        (port 4180)             │\n└───────┬────────────────────────┘\n        │\n        ▼\n┌────────────────────────────────┐\n│           Pod                  │\n│  ┌──────────────────────────┐ │\n│  │  OAuth2 Proxy Sidecar    │ │\n│  │  :4180                   │ │\n│  └─────────┬────────────────┘ │\n│            │ localhost         │\n│            ▼                   │\n│  ┌──────────────────────────┐ │\n│  │  Your Application        │ │\n│  │  :8080                   │ │\n│  └──────────────────────────┘ │\n└────────────────────────────────┘\n```\n\n### How It Works\n\n1. **Traffic arrives** at Istio Gateway with TLS termination\n2. **VirtualService routes** to Service port 4180\n3. **OAuth2 Proxy sidecar** receives request:\n   - ❌ No cookie? → Redirect to OAuth provider sign-in\n   - ✅ Valid cookie? → Proxy to app on `localhost:8080`\n4. **Application receives** request with injected headers:\n   - `X-Auth-Request-User`: `john.doe`\n   - `X-Auth-Request-Email`: `john.doe@example.com`\n   - `X-Auth-Request-Access-Token`: `gho_xxxx...`\n\n### Why Sidecar Pattern?\n\n| Benefit | Description |\n|---------|-------------|\n| **Simple** | No complex Istio ext_authz or EnvoyFilter configuration |\n| **Isolated** | Each app has its own OAuth configuration |\n| **Debuggable** | Logs and metrics co-located with your app |\n| **Flexible** | Different OAuth providers per application |\n| **Portable** | Easy to migrate apps between clusters |\n\nSee [Architecture Documentation](https://ianlintner.github.io/authproxy/architecture/overview/) for detailed diagrams.\n\n## 🔧 Configuration\n\n### OAuth Providers\n\nConfigure your OAuth provider in the Helm values:\n\n=== \"GitHub\"\n    ```yaml\n    oauth:\n      provider: github\n      clientID: Ov23li1234567890\n      clientSecret: your-secret\n      github:\n        org: \"my-company\"  # Optional: restrict to org\n        team: \"engineering\"  # Optional: restrict to team\n    ```\n\n=== \"Google\"\n    ```yaml\n    oauth:\n      provider: google\n      clientID: 1234567890-abc123.apps.googleusercontent.com\n      clientSecret: your-secret\n      google:\n        hostedDomain: \"example.com\"  # Optional: restrict to domain\n    ```\n\n=== \"Azure AD\"\n    ```yaml\n    oauth:\n      provider: azure\n      clientID: your-app-id\n      clientSecret: your-secret\n      azure:\n        tenant: your-tenant-id\n    ```\n\nSee [OAuth Provider Documentation](https://ianlintner.github.io/authproxy/providers/github/) for detailed setup guides.\n\n### Custom Sign-in Pages\n\nCustomize the sign-in page with your branding:\n\n```yaml\ncustomTemplates:\n  enabled: true\n  brandName: \"My Company SSO\"\n  logo: \"\u003cbase64-encoded-logo\u003e\"\n```\n\nSee [Custom Templates Guide](https://ianlintner.github.io/authproxy/guide/custom-templates/).\n\n### Advanced Configuration\n\n```yaml\n# Session settings\nsession:\n  cookieExpire: 168h  # 7 days\n  cookieRefresh: 1h   # Refresh interval\n\n# Email restrictions\nemail:\n  domains:\n    - \"example.com\"\n    - \"partner.com\"\n\n# Extra arguments to oauth2-proxy\nextraArgs:\n  - --skip-auth-regex=^/health\n  - --ssl-upstream-insecure-skip-verify\n```\n\nFull configuration reference: [Configuration Options](https://ianlintner.github.io/authproxy/reference/configuration/)\n\n## 🚀 Adding Your Applications\n\n### Option 1: Use the Helper Script\n\n```bash\n./scripts/add-app.sh \u003capp-name\u003e \u003cnamespace\u003e \u003capp-port\u003e \u003cdomain\u003e\n\n# Example:\n./scripts/add-app.sh my-api default 8080 api.example.com\n```\n\n### Option 2: Manual Configuration\n\nAdd the oauth2-proxy sidecar to your deployment:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: my-app\nspec:\n  template:\n    spec:\n      containers:\n      # OAuth2 Proxy sidecar\n      - name: oauth2-proxy\n        image: quay.io/oauth2-proxy/oauth2-proxy:v7.6.0\n        args:\n          - --config=/etc/oauth2-proxy/oauth2_proxy.cfg\n        env:\n          - name: OAUTH2_PROXY_UPSTREAMS\n            value: \"http://127.0.0.1:8080\"\n        ports:\n          - containerPort: 4180\n        volumeMounts:\n          - name: oauth2-proxy-config\n            mountPath: /etc/oauth2-proxy\n          - name: oauth2-proxy-templates\n            mountPath: /templates\n      \n      # Your application\n      - name: app\n        image: my-app:latest\n        ports:\n          - containerPort: 8080\n      \n      volumes:\n        - name: oauth2-proxy-config\n          configMap:\n            name: oauth2-proxy-sidecar-config\n        - name: oauth2-proxy-templates\n          configMap:\n            name: oauth2-proxy-templates\n```\n\nComplete guide: [Adding Applications](https://ianlintner.github.io/authproxy/guide/adding-apps/)\n\n## 🔍 Accessing User Information\n\nYour application automatically receives user information via HTTP headers:\n\n### Available Headers\n\n| Header | Description | Example |\n|--------|-------------|---------|\n| `X-Auth-Request-User` | Username | `john.doe` |\n| `X-Auth-Request-Email` | Email address | `john.doe@example.com` |\n| `X-Auth-Request-Preferred-Username` | Preferred username | `johndoe` |\n| `X-Auth-Request-Access-Token` | OAuth access token | `gho_xxxx...` |\n| `X-Forwarded-User` | User identifier | `john.doe` |\n| `X-Forwarded-Email` | Email address | `john.doe@example.com` |\n| `Authorization` | Bearer token | `Bearer gho_xxxx...` |\n\n### Code Examples\n\n=== \"Python / Flask\"\n    ```python\n    from flask import Flask, request\n    \n    app = Flask(__name__)\n    \n    @app.route('/')\n    def index():\n        user = request.headers.get('X-Auth-Request-User')\n        email = request.headers.get('X-Auth-Request-Email')\n        return f'Hello {user} ({email})!'\n    \n    @app.route('/admin')\n    def admin():\n        email = request.headers.get('X-Auth-Request-Email')\n        if not email.endswith('@example.com'):\n            return 'Forbidden', 403\n        return 'Admin Panel'\n    ```\n\n=== \"Node.js / Express\"\n    ```javascript\n    const express = require('express');\n    const app = express();\n    \n    app.get('/', (req, res) =\u003e {\n      const user = req.headers['x-auth-request-user'];\n      const email = req.headers['x-auth-request-email'];\n      res.send(`Hello ${user} (${email})!`);\n    });\n    \n    app.get('/admin', (req, res) =\u003e {\n      const email = req.headers['x-auth-request-email'];\n      if (!email.endsWith('@example.com')) {\n        return res.status(403).send('Forbidden');\n      }\n      res.send('Admin Panel');\n    });\n    \n    app.listen(8080);\n    ```\n\n=== \"Go\"\n    ```go\n    package main\n    \n    import (\n        \"fmt\"\n        \"net/http\"\n    )\n    \n    func handler(w http.ResponseWriter, r *http.Request) {\n        user := r.Header.Get(\"X-Auth-Request-User\")\n        email := r.Header.Get(\"X-Auth-Request-Email\")\n        fmt.Fprintf(w, \"Hello %s (%s)!\", user, email)\n    }\n    \n    func main() {\n        http.HandleFunc(\"/\", handler)\n        http.ListenAndServe(\":8080\", nil)\n    }\n    ```\n\n## 📊 Monitoring \u0026 Observability\n\n### Health Checks\n\nOAuth2-proxy exposes health endpoints:\n\n- `GET /ping` - Liveness check\n- `GET /ready` - Readiness check\n\n### Prometheus Metrics\n\nMetrics available at `/metrics`:\n\n```\noauth2_proxy_requests_total\noauth2_proxy_authentication_attempts_total\noauth2_proxy_authentication_failures_total\noauth2_proxy_cookies_expired_total\n```\n\n### Logs\n\nView sidecar logs:\n\n```bash\n# View oauth2-proxy logs\nkubectl logs -n default \u003cpod-name\u003e -c oauth2-proxy\n\n# View application logs\nkubectl logs -n default \u003cpod-name\u003e -c app\n\n# Follow both\nkubectl logs -n default \u003cpod-name\u003e --all-containers -f\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eRedirect loop / Endless redirects\u003c/b\u003e\u003c/summary\u003e\n\n**Cause**: Callback URL mismatch\n\n**Solution**: Ensure callback URL in OAuth provider matches:\n```\nhttps://auth.example.com/oauth2/callback\n```\n\nCheck deployment env var:\n```bash\nkubectl get deployment -o yaml | grep REDIRECT_URL\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCookie not persisting / Sign in every time\u003c/b\u003e\u003c/summary\u003e\n\n**Cause**: Cookie domain mismatch\n\n**Solution**: Verify cookie domain is `.example.com`:\n```bash\nkubectl get configmap oauth2-proxy-sidecar-config -o yaml | grep cookie_domains\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e404 Not Found on protected paths\u003c/b\u003e\u003c/summary\u003e\n\n**Cause**: VirtualService routing to wrong port\n\n**Solution**: Verify VirtualService routes to port 4180:\n```bash\nkubectl get virtualservice \u003capp-name\u003e -o yaml\n```\n\nShould have:\n```yaml\ndestination:\n  host: \u003capp-name\u003e\n  port:\n    number: 4180  # oauth2-proxy port\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eConnection refused to localhost:8080\u003c/b\u003e\u003c/summary\u003e\n\n**Cause**: Application not listening on localhost\n\n**Solution**: Ensure app container listens on `0.0.0.0:8080` or `127.0.0.1:8080`\n\n\u003c/details\u003e\n\nSee [Troubleshooting Guide](https://ianlintner.github.io/authproxy/guide/troubleshooting/) for more solutions.\n\n## 📁 Repository Structure\n\n```\nauthproxy/\n├── docs/                      # MkDocs documentation\n│   ├── getting-started/      # Installation \u0026 quick start\n│   ├── architecture/         # Architecture with diagrams\n│   ├── guide/                # User guides\n│   ├── providers/            # OAuth provider setup\n│   └── reference/            # API \u0026 config reference\n├── helm/\n│   └── oauth2-sidecar/       # Helm chart\n│       ├── templates/        # Kubernetes templates\n│       ├── values.yaml       # Default values\n│       └── Chart.yaml        # Chart metadata\n├── k8s/\n│   ├── base/                 # Base resources\n│   │   ├── istio/           # Gateway, VirtualService\n│   │   └── oauth2-proxy/    # ConfigMaps, templates\n│   └── apps/\n│       └── example-app/      # Complete working example\n├── scripts/\n│   ├── add-app.sh           # Add auth to existing apps\n│   ├── setup.sh             # Initial cluster setup\n│   └── validate.sh          # Validation checks\n├── examples/                 # Example configurations\n│   └── simple-app/          # Minimal example\n├── mkdocs.yml               # Documentation config\n└── README.md                # This file\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please see [Contributing Guide](https://ianlintner.github.io/authproxy/contributing/).\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/ianlintner/authproxy.git\ncd authproxy\n\n# Install documentation dependencies\npip install -r docs/requirements.txt\n\n# Serve docs locally\nmkdocs serve\n\n# Run validation\n./scripts/validate.sh\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianlintner%2Fauthproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fianlintner%2Fauthproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianlintner%2Fauthproxy/lists"}