tutorial

Monitoring Dex IDP with Vigilmon: Health Checks, OIDC Connector Availability, SSL Certificates & Database Connectivity

How to monitor Dex self-hosted OpenID Connect identity provider with Vigilmon — health endpoint checks, upstream connector availability, SSL certificate monitoring, and database connectivity.

Dex is the self-hosted OpenID Connect (OIDC) identity provider and OAuth2 server that bridges your upstream identity stores — LDAP directories, GitHub, Google, SAML providers — into a unified token-issuing endpoint. When Dex fails, every application relying on it for authentication loses the ability to issue or verify tokens. Because Dex is TLS-required for OIDC, even a certificate expiry silently breaks all client connections before anyone notices. Vigilmon gives you external visibility into Dex's availability, upstream connector health, SSL certificates, and database connectivity so you catch failures before your users do.

What You'll Build

  • A monitor on Dex's /healthz health endpoint
  • An OIDC discovery document check to validate the full OIDC layer
  • SSL certificate monitoring for your Dex domain
  • A metrics endpoint availability check
  • An alerting setup with runbook guidance for each failure mode

Prerequisites

  • A running Dex instance (default port :5556) with at least one connector configured
  • A Dex domain accessible over HTTPS (e.g., https://dex.example.com)
  • A free account at vigilmon.online

Step 1: Verify Dex's Health Endpoint

Dex exposes a /healthz endpoint that confirms the server process is running and the HTTP listener is accepting connections:

curl https://dex.example.com/healthz

A healthy Dex returns:

ok

The /healthz endpoint is intentionally minimal — it confirms the Dex process is alive and responding. It does not verify upstream connector reachability or database connectivity, which you will add in subsequent steps.

Default port: Dex listens on :5556 by default. If you expose it behind a reverse proxy, replace the port with your public URL.

Step 2: Create a Vigilmon HTTP Monitor for the Health Endpoint

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: https://dex.example.com/healthz.
  3. Check interval: 60 seconds.
  4. Response timeout: 10 seconds.
  5. Expected status: 200.
  6. Keyword: ok (the literal body text Dex returns).
  7. Click Save.

Set alerts to trigger after 1 consecutive failure — Dex is authentication infrastructure and a single failure means users cannot log in.

Step 3: Monitor the OIDC Discovery Endpoint

The OIDC discovery document at /.well-known/openid-configuration is what all OAuth2/OIDC clients fetch to obtain token endpoints, JWKS URIs, and supported scopes. When this endpoint is missing or malformed, clients cannot complete authentication flows even if Dex itself is running:

curl https://dex.example.com/.well-known/openid-configuration

A healthy response returns JSON containing issuer, authorization_endpoint, and token_endpoint fields. Add this monitor:

  1. Add Monitor → HTTP.
  2. URL: https://dex.example.com/.well-known/openid-configuration.
  3. Check interval: 60 seconds.
  4. Expected status: 200.
  5. Keyword: token_endpoint (always present in a valid OIDC discovery document).
  6. Label: Dex OIDC Discovery.
  7. Click Save.

This check validates the full OIDC stack — if Dex's gRPC server, storage layer, or configuration is broken, the discovery document will either fail to return or return an invalid response.

Step 4: Monitor the Metrics Endpoint

Dex exposes a Prometheus-compatible /metrics endpoint on the same port. While your primary monitoring uses the health and discovery endpoints, checking that /metrics responds validates that Dex's internal telemetry subsystem is healthy:

curl https://dex.example.com/metrics | head -5

Add this monitor:

  1. Add Monitor → HTTP.
  2. URL: https://dex.example.com/metrics.
  3. Check interval: 5 minutes.
  4. Expected status: 200.
  5. Keyword: dex_ (Dex prefixes all its metrics with dex_).
  6. Label: Dex Metrics Endpoint.
  7. Click Save.

Access control: Some Dex deployments restrict /metrics to internal networks. If the endpoint is not publicly accessible, monitor it through an internal uptime check or skip this step in favour of the health and discovery monitors.

Step 5: Monitor SSL Certificates

OIDC requires TLS, and every OAuth2 client in your ecosystem will immediately break if Dex's certificate expires. Browsers and OIDC libraries enforce certificate validation strictly, making this one of the highest-impact failure modes to watch:

  1. Add Monitor → SSL Certificate.
  2. Domain: dex.example.com (your Dex domain).
  3. Alert when expiry is within: 30 days.
  4. Alert again at: 14 days, 7 days, 3 days, 1 day.
  5. Click Save.

A 30-day warning gives you time to renew certificates manually if your ACME automation is broken. Dex serving an expired certificate causes all OIDC clients to fail with x509: certificate has expired — often silent until users start complaining.

Step 6: Monitor Upstream Connector Availability

Dex forwards authentication to upstream connectors: LDAP directories, GitHub OAuth apps, Google Workspace, or SAML providers. If your primary connector is down, Dex will return errors during the authorization flow even though all Dex endpoints return 200. Monitor your upstream connectors independently:

LDAP / Active Directory:

  • Add a TCP port monitor to your LDAP server (ldap.example.com:389 or :636).
  • In Vigilmon: Add Monitor → TCP Port, enter the host and port, 60-second interval.

GitHub / Google (external connectors):

  • These are external SaaS services; monitor the Dex authorization endpoint with a redirect check instead.
  • Add a monitor on https://dex.example.com/auth — a 400 or 302 (redirect to upstream) confirms Dex's auth layer is routing correctly.

SAML IdP:

  • Add an HTTP monitor to your SAML metadata URL to confirm the IdP is publishing valid metadata.

Step 7: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | /healthz | Non-200 or body not ok | Check Dex process (systemctl status dex or pod logs); verify storage backend | | OIDC Discovery | Non-200 or token_endpoint missing | Check Dex config (config.yaml); verify gRPC server is listening | | Metrics endpoint | Non-200 | Minor — check Dex logs for internal errors; usually not user-facing | | SSL certificate | < 30 days | Renew certificate; verify ACME cron or cert-manager is running | | LDAP / upstream | TCP failure | Check LDAP server health; Dex will fail auth flows for that connector |

Common Dex Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Dex process crash | /healthz unreachable; alert within 60 s | | SQLite/PostgreSQL database unreachable | OIDC discovery returns error; health may still return ok | | TLS certificate expires | SSL monitor alerts at 30-day threshold; all OIDC clients break | | Config error after upgrade | OIDC discovery returns 500 or malformed JSON | | LDAP connector down | LDAP TCP monitor fires; Dex health stays green | | Wrong issuer URL configured | OIDC discovery returns mismatched issuer; clients reject tokens | | Pod OOMKilled in Kubernetes | /healthz becomes unreachable; alert within 60 s | | Port conflict on restart | /healthz and discovery fail simultaneously |

Dex is the authentication gateway for every application in your SSO setup. An unmonitored Dex deployment can silently break logins for dozens of services with a single misconfiguration or certificate expiry. Vigilmon's layered checks — health endpoint, OIDC discovery, SSL certificate, and upstream connectors — give you complete external visibility so you're alerted within minutes rather than discovering the outage from a flood of user complaints.

Start monitoring Dex in under 5 minutes — register free at vigilmon.online.

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