Monitoring Traefik Forward Auth with Vigilmon

Traefik Forward Auth (thomseddon/traefik-forward-auth) is the most popular SSO middleware in self-hosted Traefik deployments. Every request to a ForwardAuth-protected service gets forwarded to it first — if the auth service goes down or becomes slow, users across all your self-hosted apps hit authentication failures simultaneously. Vigilmon gives you the health checks, latency monitoring, and alert routing to catch Traefik Forward Auth problems the moment they happen.

What You'll Set Up

• HTTP health check on the ForwardAuth endpoint (port 4181)
• Google OAuth2 connectivity monitor
• TLS certificate expiry alert for protected Traefik entrypoints
• Cron heartbeat for the Forward Auth process
• Alert channels for SSO outage notifications

Prerequisites

• Traefik running with ForwardAuth middleware configured
• traefik-forward-auth service accessible (default port 4181)
• A free Vigilmon account

Why Monitor Traefik Forward Auth?

Traefik Forward Auth intercepts every request to every ForwardAuth-protected route. When it fails:

• All protected services return authentication errors — a single auth service outage takes down every ForwardAuth middleware chain simultaneously
• OAuth2 callback failures strand users mid-login — CSRF state mismatches or Google OAuth2 connectivity loss cause redirect loops
• Mass session expiry causes redirect storms — if the secret changes or the service restarts with bad config, all active sessions invalidate at once
• Latency spikes directly delay all page loads — Traefik waits synchronously for ForwardAuth to respond before serving each protected request

Monitoring the Forward Auth service is separate from monitoring your individual Traefik-proxied services — because one auth outage breaks them all.

Key Metrics to Monitor

| Metric | Why It Matters | |---|---| | /_oauth HTTP 302 | Primary liveness signal — service up and redirecting unauthenticated probes | | Google OAuth2 connectivity | Authentication fails if accounts.google.com is unreachable | | ForwardAuth response latency | Added to every request for every protected service | | TLS certificate expiry | Expired certs on Traefik entrypoints break HTTPS-only services | | Session cookie validation rate | Session expiry storm after config change causes mass re-authentication |

Step 1: Monitor the ForwardAuth Health Endpoint

Traefik Forward Auth serves on port 4181. An unauthenticated GET to /_oauth returns HTTP 302 (redirect to Google) when the service is healthy.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the ForwardAuth URL:
   • Internal: http://traefik-forward-auth:4181/_oauth
   • External (if exposed): https://auth.yourdomain.com/_oauth
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 302.
6. Click Save.

If the service is down, you get a connection refused or timeout. If misconfigured, you may get 500 instead of 302. Either way Vigilmon flags it.

Step 2: Monitor Google OAuth2 Connectivity

Traefik Forward Auth communicates with Google's OAuth2 endpoints to exchange authorization codes and validate tokens. If Google's endpoints are unreachable, no new logins succeed.

1. Click Add Monitor in Vigilmon.
2. Set Type to HTTP / HTTPS.
3. Enter: https://accounts.google.com/.well-known/openid-configuration
4. Set Expected HTTP status to 200.
5. Set Check interval to 5 minutes.
6. Click Save.

Add a second monitor for the token endpoint:

1. Click Add Monitor.
2. Enter: https://oauth2.googleapis.com/token
3. Set Expected HTTP status to 405 (POST-only endpoint returns 405 for GET probes — confirming reachability without triggering an auth flow).
4. Set Check interval to 5 minutes.
5. Click Save.

Step 3: TLS Certificate Expiry Alert

Traefik typically terminates TLS for all protected services. An expired certificate on a Traefik entrypoint breaks HTTPS access for every service behind it.

For each domain served by your Traefik instance:

1. Click Add Monitor in Vigilmon.
2. Set Type to HTTP / HTTPS.
3. Enter: https://yourdomain.com/
4. Enable SSL certificate expiry check.
5. Set Alert threshold to 30 days.
6. Click Save.

If you use Traefik's ACME/Let's Encrypt integration, also monitor for failed certificate renewals by watching for 404 or connection errors on domains that previously resolved.

Step 4: Process Heartbeat

For Docker-based deployments, add a sidecar heartbeat that pings Vigilmon while the Forward Auth container is running:

# docker-compose.yml
services:
  traefik-forward-auth:
    image: thomseddon/traefik-forward-auth:2
    environment:
      - DEFAULT_PROVIDER=google
      - PROVIDERS_GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
      - PROVIDERS_GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
      - SECRET=${COOKIE_SECRET}
      - WHITELIST=${ALLOWED_EMAIL}

  forward-auth-heartbeat:
    image: curlimages/curl:latest
    restart: always
    command: >
      sh -c "while true; do
        curl -fsS https://vigilmon.online/beat/YOUR_HEARTBEAT_ID > /dev/null;
        sleep 300;
      done"
    depends_on:
      - traefik-forward-auth

Create the heartbeat in Vigilmon under Heartbeats, set the expected interval to 10 minutes, and replace YOUR_HEARTBEAT_ID above.

Step 5: Monitor ForwardAuth Latency

Traefik Forward Auth adds synchronous latency to every protected request. Monitoring this endpoint's response time directly reflects impact on end users.

1. Edit your ForwardAuth health monitor in Vigilmon.
2. Enable Response time tracking.
3. Set a Response time alert at 500ms — if auth validation takes longer than half a second, users notice it on every page load.
4. Click Save.

Track the P95 response time trend. A spike usually indicates high CPU load on the auth container, Google OAuth2 API slowness, or a session validation bottleneck.

Step 6: Configure Alert Channels

ForwardAuth outages affect every user of every protected service. Route these alerts to immediate on-call channels:

1. Go to Settings → Alert Channels in Vigilmon.
2. Add a Slack integration pointing to your #incidents channel.
3. Add a PagerDuty or OpsGenie integration for out-of-hours alerts.
4. Return to the ForwardAuth health monitor and assign both channels.
5. Set Google OAuth2 monitor to also alert on the same channels with a 2-check grace period.

Step 7: Verify the Monitoring Setup

Test the alert chain works before you need it:

1. Stop the Forward Auth container: docker stop traefik-forward-auth
2. Verify Vigilmon flags the health monitor red within 2 minutes.
3. Confirm the Slack alert fires.
4. Restart the container: docker start traefik-forward-auth
5. Confirm Vigilmon shows the monitor recovering and fires a recovery notification.

Troubleshooting Common Forward Auth Issues

All protected Traefik routes returning authentication errors Check the container is running: docker logs traefik-forward-auth. Common startup failures: missing SECRET, invalid Google client credentials, or AUTH_HOST mismatch. Verify docker ps shows the container as healthy.

OAuth2 callback returning "invalid state parameter" This is a CSRF error — the state parameter in the callback doesn't match what the service signed. Causes: multiple Forward Auth replicas without a shared SECRET, or container restart clearing in-memory state during an active OAuth2 flow. Ensure all replicas use the same SECRET environment variable.

Mass session expiry after deployment If you rotate SECRET without a rolling deployment, all existing session cookies become invalid simultaneously. Use a blue-green deployment when rotating secrets, or implement LEGACY_COOKIE=true during the transition period.

Domain whitelist rejecting valid users Check the WHITELIST or DOMAIN environment variables. Traefik Forward Auth matches WHITELIST against the exact email address and DOMAIN against the email domain. Both can be set; either match grants access.

Conclusion

Traefik Forward Auth is a single point of authentication for your entire Traefik proxy ecosystem. A short outage breaks SSO for every ForwardAuth-protected route simultaneously — and because Traefik waits synchronously for the auth response, latency spikes there degrade user experience for all protected services.

With Vigilmon monitoring the /_oauth endpoint, Google OAuth2 connectivity, TLS certificate expiry, and a process heartbeat, you catch auth failures before they cascade. Start with the health check monitor and TLS alert — those two detect the most common failure modes in under two minutes.

Sign up for Vigilmon and add your ForwardAuth endpoint as the first monitor.