Quick Start¶

Get OAuth2 authentication running on your Kubernetes cluster in under 10 minutes.

Prerequisites¶

Before you begin, ensure you have:

• Kubernetes cluster (1.20+) with kubectl access
• Istio service mesh installed (1.14+)
• Helm 3 installed
• A domain with DNS access (e.g., example.com)
• OAuth application credentials (we'll use GitHub in this guide)

Step 1: Register OAuth Application¶

Step 2: Configure DNS¶

Point a wildcard DNS record to your Istio ingress gateway:

# Get your Istio ingress gateway IP
kubectl get svc -n istio-system istio-ingressgateway

# Create DNS A record
# Name: *.example.com
# Type: A
# Value: <INGRESS_IP>

Step 3: Install with Helm¶

Create a values file with your configuration:

# Domain configuration
domain: example.com
cookieDomain: .example.com

# OAuth provider configuration
oauth:
  provider: github
  clientID: "your-client-id"
  clientSecret: "your-client-secret"
  # Cookie secret will be auto-generated

# Istio configuration
istio:
  enabled: true
  gateway:
    create: true
    name: oauth2-gateway
    hosts:
      - "*.example.com"
    tls:
      mode: SIMPLE
      credentialName: wildcard-tls  # Your TLS cert secret

# Custom branding
customTemplates:
  enabled: true
  brandName: "My Company SSO"

Install the Helm chart:

helm install oauth2-sidecar ./helm/oauth2-sidecar \
  --values my-values.yaml \
  --namespace default \
  --create-namespace

Step 4: Deploy Example Application¶

Deploy the example app to test the setup:

kubectl apply -k k8s/apps/example-app/

Wait for the pod to be ready:

kubectl get pods -l app=example-app -w

Step 5: Test Authentication¶

Open your browser and navigate to:

https://example-app.example.com

You should see:

1. Sign-in page with your provider button
2. Click the button → Redirects to OAuth provider
3. Authorize the app → Redirects back to your app
4. Success! You're now authenticated

sequenceDiagram
    autonumber
    participant Browser
    participant App
    participant OAuth2Proxy
    participant GitHub

    Browser->>App: GET /
    App->>OAuth2Proxy: Check auth
    OAuth2Proxy-->>Browser: 200 Sign-in page
    Browser->>OAuth2Proxy: Click GitHub button
    OAuth2Proxy-->>Browser: 302 Redirect to GitHub
    Browser->>GitHub: Authorize
    GitHub-->>Browser: 302 Callback
    Browser->>OAuth2Proxy: GET /oauth2/callback?code=...
    OAuth2Proxy->>GitHub: Exchange code
    GitHub-->>OAuth2Proxy: Access token
    OAuth2Proxy-->>Browser: 302 Set cookie + redirect
    Browser->>App: GET / (with cookie)
    App->>OAuth2Proxy: Check auth
    OAuth2Proxy-->>App: Forward with headers
    App-->>Browser: 200 App content

Step 6: Access User Information¶

Your application receives user information via HTTP headers:

# Test with curl (after authenticating in browser)
curl -v https://example-app.example.com/headers \
  -H "Cookie: _oauth2_proxy=<your-cookie>"

Headers available to your app:

• X-Auth-Request-User: Username
• X-Auth-Request-Email: Email address
• X-Auth-Request-Preferred-Username: Preferred username
• X-Forwarded-User: User identifier
• X-Forwarded-Email: Email address

Example in your app:

from flask import Flask, request

app = Flask(__name__)

@app.route('/')
def index():
    user_email = request.headers.get('X-Auth-Request-Email')
    username = request.headers.get('X-Auth-Request-User')
    return f'Hello {username} ({user_email})!'

const express = require('express');
const app = express();

app.get('/', (req, res) => {
  const userEmail = req.headers['x-auth-request-email'];
  const username = req.headers['x-auth-request-user'];
  res.send(`Hello ${username} (${userEmail})!`);
});

package main

import (
    "fmt"
    "net/http"
)

func handler(w http.ResponseWriter, r *http.Request) {
    email := r.Header.Get("X-Auth-Request-Email")
    user := r.Header.Get("X-Auth-Request-User")
    fmt.Fprintf(w, "Hello %s (%s)!", user, email)
}

func main() {
    http.HandleFunc("/", handler)
    http.ListenAndServe(":8080", nil)
}

What's Next?¶

• Add authentication to your own app
• Customize the sign-in page
• Learn about the architecture
• Configure advanced options

Troubleshooting¶

For more help, see the Troubleshooting Guide.