How to Monitor OAuth2 Proxy with Vigilmon

OAuth2 Proxy is a reverse proxy that enforces OAuth2 and OIDC authentication in front of your internal services. Deployed as a sidecar, a standalone gateway, or an ingress annotation, it handles the token exchange so your backend never has to. When OAuth2 Proxy is healthy, your users log in invisibly. When it fails, every service behind it returns 401 or a redirect loop, and your application appears broken regardless of whether the backend itself is running.

Vigilmon gives you external visibility into OAuth2 Proxy's availability, upstream reachability, and authentication flow health before users discover the outage. This tutorial walks through building a complete monitoring setup.

Why Monitoring OAuth2 Proxy Matters

OAuth2 Proxy sits at the authentication boundary. A failure here has an amplified blast radius compared to a single service going down:

• All protected services fail simultaneously — a single proxy instance or deployment failing takes down everything behind it
• Silent auth failures — a misconfigured OIDC provider URL or expired client secret causes login loops rather than obvious error pages
• Upstream provider outages — if the identity provider (Google, GitHub, Keycloak) is unreachable, OAuth2 Proxy cannot exchange tokens and all new logins fail
• Cookie or session expiry edge cases — a misconfigured cookie secret causes session invalidation across all users on restart
• Certificate rotation — expired TLS certificates on either OAuth2 Proxy or the upstream provider silently break the OIDC flow

Internal process monitoring tells you the process is running. Vigilmon tells you whether authentication is actually working for your users.

Step 1: Verify the Built-In Ping Endpoint

OAuth2 Proxy ships with a built-in health endpoint at /ping (and optionally /ready). By default it returns 200 OK with body OK. Verify it is accessible:

# Direct probe to the proxy
curl -i https://auth.example.com/ping
# HTTP/1.1 200 OK
# OK

If you have deployed OAuth2 Proxy behind an ingress or load balancer, probe through that layer — not directly to the pod — so the monitor reflects the same path your users take.

Configure the /ping Endpoint

In your OAuth2 Proxy configuration (oauth2-proxy.cfg or environment variables):

# oauth2-proxy.cfg
ping-path = "/ping"
ping-user-agent = "VigilmonHealthCheck/1.0"

Or via environment variable:

OAUTH2_PROXY_PING_PATH=/ping

The /ping endpoint bypasses authentication intentionally — it is safe to expose to external monitoring without credentials.

Step 2: Add a Vigilmon HTTP Monitor for the Proxy Health

1. Log in to vigilmon.online and go to Monitors → New Monitor
2. Choose HTTP / HTTPS
3. Set the URL to: https://auth.example.com/ping
4. Set the check interval to 1 minute
5. Under Expected response, configure:
   • Status code: 200
   • Response body contains: OK
   • Response time threshold: 500ms
6. Set the monitor name: [oauth2-proxy] /ping
7. Under Alert channels, assign your Slack or PagerDuty channel
8. Save the monitor

This monitor confirms that OAuth2 Proxy is up and responding through the full network path. A failure here means new authentication attempts will fail immediately.

What the /ping Monitor Catches

| Failure | Process Monitor | Vigilmon | |---|---|---| | OAuth2 Proxy process crash | ✓ | ✓ | | Ingress misconfiguration | ✗ | ✓ | | TLS certificate expiry on auth domain | ✗ | ✓ | | Network path blocked by firewall rule | ✗ | ✓ | | Kubernetes pod crash loop | ✗ | ✓ |

Step 3: Monitor the Upstream Service Reachability

OAuth2 Proxy forwards authenticated requests to an upstream service. If the upstream is unreachable, authenticated users will still get through OAuth2 but then hit a 502 or 504 from the proxy. Add a monitor for the upstream health endpoint:

# Probe your upstream service (bypassing OAuth2 Proxy directly)
curl -i https://internal-api.example.com/health

Configure a second Vigilmon monitor:

1. URL: https://internal-api.example.com/health (or your upstream's health endpoint)
2. Interval: 1 minute
3. Expected status: 200
4. Monitor name: [upstream] internal-api /health

Correlating Upstream vs. Proxy Failures

By running both monitors, you can immediately distinguish:

• Both monitors down → infrastructure/network issue upstream of OAuth2 Proxy
• Only OAuth2 Proxy monitor down → proxy-layer failure (check pods, ingress, TLS)
• Only upstream monitor down → backend failure (the proxy is fine, the app is not)
• OAuth2 Proxy up, upstream up, but users getting 502 → proxy-to-upstream routing misconfiguration

Step 4: Monitor the OIDC Provider (Identity Provider Reachability)

OAuth2 Proxy depends on an upstream identity provider — Google, GitHub, Keycloak, Okta, or any OIDC-compatible IdP. If the provider's discovery endpoint becomes unreachable, OAuth2 Proxy cannot validate tokens and will reject all new logins.

Monitor the OIDC discovery endpoint of your IdP:

# Generic OIDC discovery endpoint
curl -i https://accounts.google.com/.well-known/openid-configuration
# Or for self-hosted Keycloak:
curl -i https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration

Add a Vigilmon monitor:

1. URL: https://<your-idp>/.well-known/openid-configuration
2. Interval: 5 minutes (provider discovery documents are stable; less frequent is fine)
3. Expected status: 200
4. Response body contains: "issuer"
5. Monitor name: [idp] oidc-discovery

If you are using a self-hosted IdP like Keycloak, Dex, or Authentik, run this monitor at 1 minute — self-hosted providers are more likely to go down.

Step 5: Monitor the Metrics Endpoint (Optional)

If you have enabled the OAuth2 Proxy metrics endpoint, it exposes Prometheus-format metrics including request rates, error counts, and session statistics. You can use Vigilmon to verify the metrics endpoint is alive even if you are scraping it with a separate Prometheus stack:

# Default metrics port
curl -i http://oauth2-proxy.internal:44180/metrics

Configure an HTTP monitor with:

• URL: http://oauth2-proxy.internal:44180/metrics (internal network, not public-facing)
• Expected body contains: oauth2_proxy_requests_total
• Interval: 5 minutes

This is a secondary signal — primarily confirms the proxy's internal state is being exposed for scraping.

Step 6: Configure Alert Routing

Authentication outages are P1 — every protected service in your stack is affected. Set up alert escalation accordingly:

1. /ping monitor → immediate Slack + PagerDuty page (P1, all-hands)
2. Upstream service monitor → Slack + email (P2, backend on-call)
3. OIDC discovery monitor → Slack (P3, new logins only affected)
4. Metrics endpoint monitor → Slack (P3, observability degraded)

In Vigilmon, set confirmation count to 2 for the /ping monitor. This prevents a single-probe flap from paging your entire on-call rotation, while still alerting within 2 minutes of a confirmed outage.

Recommended Alert Thresholds

| Monitor | Latency Alert | Status Code Alert | |---|---|---| | /ping | > 500ms | Any non-200 | | Upstream /health | > 2000ms | Any non-200 | | OIDC discovery | > 3000ms | Any non-200 |

Step 7: Group Monitors in a Status Page

Create a Vigilmon Status Page for your authentication infrastructure:

1. Go to Status Pages → New Status Page
2. Add a group: Authentication Layer
3. Add monitors to the group:
   • [oauth2-proxy] /ping
   • [idp] oidc-discovery
   • [upstream] internal-api /health
4. Set visibility to Internal (share with your engineering team only)
5. Enable email subscriptions for your on-call rotation

This gives your team a single URL to check when users report login failures — the status page immediately reveals which layer is at fault.

Summary

OAuth2 Proxy is the authentication gate for your entire protected surface area. A single failure takes down every service behind it. Vigilmon gives you:

| Monitor | What It Detects | |---|---| | /ping HTTP monitor | Proxy process, network path, TLS, ingress | | Upstream /health monitor | Backend availability independent of auth | | OIDC discovery monitor | Identity provider reachability for new logins | | Metrics endpoint monitor | Internal proxy observability |

Get started free at vigilmon.online — your first OAuth2 Proxy monitor is running in under two minutes.