tutorial

Monitoring Vouch Proxy with Vigilmon

Vouch Proxy adds OAuth2/OIDC SSO to any Nginx-fronted service — but if the auth service goes down, every protected resource returns 401. Here's how to monitor Vouch Proxy health, auth throughput, and OIDC connectivity with Vigilmon.

Vouch Proxy is the glue that lets Nginx delegate authentication to Google, GitHub, Okta, Keycloak, or any OIDC provider. Every request to a protected resource hits Vouch Proxy first via Nginx's auth_request directive — which means a downed Vouch Proxy instance immediately breaks SSO for every service behind it. Vigilmon gives you the uptime checks, latency tracking, and alert routing you need to catch Vouch Proxy problems before your users do.

What You'll Set Up

  • HTTP health check on Vouch Proxy's /healthcheck endpoint (port 9090)
  • OIDC provider connectivity monitor
  • TLS certificate expiry alert for the Vouch Proxy endpoint
  • Cron heartbeat for the Vouch Proxy process
  • Alert channels for authentication outage notifications

Prerequisites

  • Vouch Proxy running and accessible (default port 9090)
  • Nginx configured with auth_request pointing to Vouch Proxy
  • A free Vigilmon account

Why Monitor Vouch Proxy?

Vouch Proxy sits in the critical path of every authenticated request. When it fails silently:

  • Nginx returns 401 for all protected resources — auth_request failures cascade to all downstream services simultaneously
  • OAuth2 callbacks stop working — users mid-login get stuck in redirect loops
  • JWT cookie validation errors accumulate — clock skew or key rotation issues corrupt active sessions
  • OIDC provider connectivity loss — if Vouch Proxy cannot reach the discovery endpoint, new logins fail even if existing sessions still work

Monitoring Vouch Proxy separately from your upstream services is essential because a single auth service failure produces widespread, confusing errors across every protected application.

Key Metrics to Monitor

| Metric | Why It Matters | |---|---| | /healthcheck HTTP 200 | Primary liveness signal — downtime blocks all auth_request validations | | OIDC discovery endpoint reachability | New logins fail if Vouch Proxy cannot fetch provider configuration | | TLS certificate expiry | Nginx must reach Vouch Proxy over HTTPS; expired cert breaks all auth | | Auth_request latency | Vouch Proxy adds latency to every protected request | | 401 response spike | Indicates authentication failures for protected resources | | Callback error rate | OAuth2 callback failures indicate OIDC provider misconfiguration |

Step 1: Monitor the Vouch Proxy Health Endpoint

Vouch Proxy exposes a /healthcheck endpoint on port 9090 that returns HTTP 200 when the service is healthy.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter the Vouch Proxy health URL: https://vouch.yourdomain.com/healthcheck
    • If running internally without TLS: http://localhost:9090/healthcheck
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

This is your primary liveness check. If it goes red, every auth_request-protected Nginx location is returning 401 to end users.

Step 2: Monitor OIDC Provider Connectivity

Vouch Proxy fetches the OIDC discovery document from your identity provider on startup and periodically during operation. If the provider is unreachable, new logins fail.

Add a separate monitor for your OIDC provider's discovery endpoint:

Google

https://accounts.google.com/.well-known/openid-configuration

GitHub (via Dex or similar)

https://dex.yourdomain.com/.well-known/openid-configuration

Keycloak

https://keycloak.yourdomain.com/realms/yourrealm/.well-known/openid-configuration

For each provider:

  1. Click Add Monitor in Vigilmon.
  2. Set Type to HTTP / HTTPS.
  3. Enter the discovery document URL.
  4. Set Expected HTTP status to 200.
  5. Set Check interval to 5 minutes (provider endpoints are stable; frequent checks waste quota).
  6. Click Save.

Step 3: TLS Certificate Expiry Alert

Nginx communicates with Vouch Proxy over HTTPS in production. An expired certificate on the Vouch Proxy endpoint causes Nginx to reject auth_request responses, breaking all SSO.

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

Step 4: Process Heartbeat via Cron

For Vouch Proxy instances that run as a systemd service, add a heartbeat so Vigilmon knows the process is still sending pings:

# /etc/systemd/system/vouch-proxy.service
[Unit]
Description=Vouch Proxy
After=network.target

[Service]
ExecStart=/usr/local/bin/vouch-proxy -config /etc/vouch/config.yml
Restart=always
RestartSec=5

# Add this to ping Vigilmon every 5 minutes
ExecStartPost=/bin/bash -c 'while true; do curl -fsS https://vigilmon.online/beat/YOUR_HEARTBEAT_ID > /dev/null; sleep 300; done &'

[Install]
WantedBy=multi-user.target

Or add a cron entry:

*/5 * * * * pgrep -x vouch-proxy && curl -fsS https://vigilmon.online/beat/YOUR_HEARTBEAT_ID

Create the heartbeat in Vigilmon under Heartbeats, set the expected interval to 10 minutes, and paste the ID into the cron above.

Step 5: Monitor the OAuth2 Callback Route

The OAuth2 callback endpoint receives the authorization code from your OIDC provider after a user logs in. Monitor it independently:

  1. Click Add Monitor in Vigilmon.
  2. Set Type to HTTP / HTTPS.
  3. Enter the callback URL: https://vouch.yourdomain.com/auth
  4. Set Expected HTTP status to 302 (Vouch Proxy redirects unauthenticated probes).
  5. Set Check interval to 5 minutes.
  6. Click Save.

A 500 or connection refused on /auth while /healthcheck is green indicates a routing or configuration issue specific to the OAuth2 flow.

Step 6: Configure Alert Channels

Vouch Proxy outages affect all users of all protected services simultaneously — route alerts to an on-call channel.

  1. Go to Settings → Alert Channels in Vigilmon.
  2. Add a Slack or PagerDuty integration for immediate on-call notification.
  3. Add an Email channel for secondary notification.
  4. Return to each monitor created above and assign both channels.

Set alert sensitivity appropriately:

  • Healthcheck monitor: alert after 1 failed check — Vouch downtime is immediately impactful
  • OIDC provider monitor: alert after 2 failed checks — brief provider blips are common
  • Certificate expiry: alert at 30 days, escalate at 7 days

Step 7: Verify the Setup End-to-End

With monitors in place, validate they work:

  1. Stop Vouch Proxy temporarily: sudo systemctl stop vouch-proxy
  2. Check that the healthcheck monitor goes red in Vigilmon within 2 minutes.
  3. Verify the alert fires on your configured channel.
  4. Restart Vouch Proxy: sudo systemctl start vouch-proxy
  5. Confirm the monitor recovers and a recovery notification fires.

Troubleshooting Common Vouch Proxy Issues

All protected Nginx routes returning 401 Check the Vouch Proxy healthcheck endpoint directly: curl -v http://localhost:9090/healthcheck. If it fails, check journalctl -u vouch-proxy for startup errors (missing config, invalid OIDC credentials, port conflict).

OAuth2 callback returning 500 Usually indicates a mismatch between the redirect URI registered with the OIDC provider and the vouch.callback setting in config.yml. Verify the callback URL in your provider's OAuth2 app settings exactly matches what Vouch Proxy expects.

JWT cookie validation errors If Vouch Proxy logs show decryption errors, check for clock skew between the server running Vouch Proxy and the OIDC provider. Use timedatectl to verify NTP sync. If running multiple Vouch instances, ensure they all share the same jwt.secret and cookie.secret values.

OIDC discovery endpoint unreachable If your provider is Keycloak or Dex running internally, ensure Vouch Proxy's network can reach it. Check /etc/hosts or DNS resolution: curl https://keycloak.yourdomain.com/.well-known/openid-configuration.

Conclusion

Vouch Proxy is a single point of authentication for every auth_request-protected Nginx service. A 60-second outage affects every user of every protected application simultaneously. With Vigilmon monitoring the healthcheck endpoint, OIDC provider connectivity, TLS certificates, and the OAuth2 callback route, you get early warning before authentication failures cascade into user-visible outages.

Start with the /healthcheck monitor and TLS expiry alert — those two alone catch the most impactful failure modes. Add OIDC provider connectivity checks and a process heartbeat to complete coverage.

Sign up for Vigilmon and add your Vouch Proxy healthcheck as the first monitor.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles