Skip to content

Authentication Quick Reference

Quick reference for common authentication tasks.

Installation

Install with Azure AD

make auth.install PROVIDER=azuread DOMAIN=example.com

Install with Google

make auth.install PROVIDER=google DOMAIN=example.com

Install with GitHub

make auth.install PROVIDER=github DOMAIN=example.com

Install with Okta SAML

make auth.install PROVIDER=okta-saml DOMAIN=example.com

Protection

Protect an app with group-based access

make auth.protect APP=myapp HOST=myapp.example.com POLICY=group:developers

Protect an app with domain restriction

make auth.protect APP=blog HOST=blog.example.com POLICY=domain:example.com

Protect an app - allow all authenticated users

make auth.protect APP=docs HOST=docs.example.com POLICY=public

Verification

Check auth module status

make auth.doctor

View oauth2-proxy logs

kubectl logs -n greenfield -l app=oauth2-proxy -f

Check protected apps

kubectl get virtualservice -n greenfield -l auth-enabled=true

View authorization policies

kubectl get authorizationpolicy -n greenfield

Troubleshooting

Redirect loop

# Check cookie domains
kubectl get configmap oauth2-proxy-config -n greenfield -o yaml

# Check redirect URL
kubectl get configmap oauth2-proxy-config -n greenfield -o jsonpath='{.data.redirect-url}'

Groups not in JWT

# Decode JWT to check claims
# Get token from browser DevTools → Application → Cookies
# Or from X-Auth-Request-Access-Token header

TOKEN="eyJ..."
echo $TOKEN | cut -d. -f2 | base64 -d | jq .

Authorization denied

# Check authorization policies
kubectl get authorizationpolicy -n greenfield -o yaml

# Check Istio sidecar logs
kubectl logs -n greenfield POD_NAME -c istio-proxy

Configuration Updates

Update oauth2-proxy configuration

kubectl edit configmap oauth2-proxy-config -n greenfield
kubectl rollout restart deployment oauth2-proxy -n greenfield

Update secrets

kubectl delete secret oauth2-proxy-secret -n greenfield
kubectl create secret generic oauth2-proxy-secret \
  --from-literal=client-id=NEW_CLIENT_ID \
  --from-literal=client-secret=NEW_CLIENT_SECRET \
  --from-literal=cookie-secret=$(openssl rand -base64 32 | head -c 32) \
  -n greenfield

Add environment variable to oauth2-proxy

kubectl set env deployment/oauth2-proxy -n greenfield \
  OAUTH2_PROXY_SKIP_OIDC_DISCOVERY=false

Provider-Specific Commands

Azure AD - Enable group claims

kubectl set env deployment/oauth2-proxy -n greenfield \
  OAUTH2_PROXY_OIDC_GROUPS_CLAIM=groups

GitHub - Restrict to organization

kubectl set env deployment/oauth2-proxy -n greenfield \
  OAUTH2_PROXY_GITHUB_ORG=your-org

Google - Restrict to domain

kubectl set env deployment/oauth2-proxy -n greenfield \
  OAUTH2_PROXY_GOOGLE_GROUP=your-company.com

Common kubectl Commands

Get all auth resources

kubectl get deployment,service,configmap,secret \
  -n greenfield -l app=oauth2-proxy

Get all Istio auth resources

kubectl get gateway,virtualservice,requestauthentication,authorizationpolicy \
  -n greenfield,istio-system

Describe oauth2-proxy deployment

kubectl describe deployment oauth2-proxy -n greenfield

Check pod status

kubectl get pods -n greenfield -l app=oauth2-proxy -o wide

Port forward to oauth2-proxy

kubectl port-forward -n greenfield svc/oauth2-proxy 4180:4180
# Access http://localhost:4180/ping

Testing Authentication

Test without auth (should get 302 redirect)

curl -v https://myapp.example.com/ 2>&1 | grep -i location

Test health endpoint (should return 200)

curl -v https://myapp.example.com/health

# After authentication, save cookies
curl -c cookies.txt https://myapp.example.com/

# Use cookies for subsequent requests
curl -b cookies.txt https://myapp.example.com/api/data

Useful Queries

List all protected applications

kubectl get virtualservice -n greenfield -l auth-enabled=true \
  -o custom-columns=NAME:.metadata.name,HOST:.spec.hosts[0]

Check which apps require specific groups

kubectl get authorizationpolicy -n greenfield -o yaml | \
  grep -A 5 "request.auth.claims\[groups\]"

Find apps with public paths

kubectl get authorizationpolicy -n greenfield -o yaml | \
  grep -B 5 "/health"

Cleanup

Remove auth from an app

kubectl delete virtualservice,authorizationpolicy,requestauthentication \
  -n greenfield -l app=myapp

Uninstall auth module

kubectl delete -k kustomize/base/auth/overlays/provider-azuread/

Remove all auth resources

kubectl delete namespace greenfield
# Or selectively:
kubectl delete deployment,service,configmap \
  -n greenfield -l app=oauth2-proxy

Emergency Procedures

Disable authentication temporarily

# Delete EnvoyFilter to bypass auth
kubectl delete envoyfilter oauth2-proxy-ext-authz -n istio-system

# Re-enable
kubectl apply -f kustomize/base/auth/base/gateway/envoyfilter-ext-authz.yaml

Allow all users temporarily

# Create temporary allow-all policy
kubectl apply -f - <<EOF
apiVersion: security.istio.io/v1beta1
kind: AuthorizationPolicy
metadata:
  name: temporary-allow-all
  namespace: greenfield
spec:
  action: ALLOW
  rules:
  - {}
EOF

# Remove when done
kubectl delete authorizationpolicy temporary-allow-all -n greenfield

Reset oauth2-proxy

# Delete and recreate
kubectl delete deployment oauth2-proxy -n greenfield
kubectl apply -k kustomize/base/auth/overlays/provider-azuread/

Resources