tutorial

How to Monitor Ory Hydra with Vigilmon

Ory Hydra is your OAuth2 and OIDC authorization server — when it fails, token issuance stops and every downstream service that trusts its JWTs breaks. Here's how to monitor Hydra's public API, admin API, JWKS endpoint, and database connectivity with Vigilmon.

Ory Hydra is a certified OpenID Connect and OAuth2 server designed for cloud-native infrastructure. It handles token issuance, token introspection, consent flows, and JWKS key rotation without storing user credentials — your application's authentication layer depends entirely on Hydra being available and healthy. When Hydra goes down, token-based authentication fails across every service that introspects or validates tokens against it.

Vigilmon gives you external visibility into Hydra's public API, admin API, JWKS endpoint availability, and the underlying database connectivity that all of these depend on. This tutorial walks through a complete monitoring setup for a production Hydra deployment.

Why Monitoring Ory Hydra Matters

Hydra is a dependency for every authenticated API call in your system. The failure modes are varied and not always obvious:

  • Public API down — token introspection, token exchange, and consent redirects all fail; users cannot authenticate or refresh sessions
  • Admin API down — automated client registration, consent management scripts, and your CI/CD OAuth client provisioning all fail silently
  • JWKS endpoint unavailable — services that cache public keys for JWT validation will eventually expire their caches and be unable to validate any tokens
  • Database connectivity loss — Hydra is stateless except for its database; losing the DB means Hydra cannot look up authorization codes, tokens, or consent sessions
  • Token introspection endpoint failure — API gateways performing introspection-based validation will reject all requests, even with valid tokens

None of these show up as "Hydra process crash" on your process monitor. Vigilmon catches them by probing the actual endpoints your services depend on.

Step 1: Understand Hydra's Endpoint Architecture

Ory Hydra exposes two distinct ports:

| Port | Purpose | Public? | |---|---|---| | 4444 (public) | Token endpoints, OIDC discovery, JWKS, authorization | Yes — internet-facing | | 4445 (admin) | Client management, consent, introspection admin | No — internal only |

You need separate Vigilmon monitors for each port because they serve different audiences and have different failure modes.

Verify both are reachable:

# Public API health check
curl -i https://hydra.example.com/.well-known/openid-configuration

# Admin API health check (internal network)
curl -i http://hydra.internal:4445/health/ready

Step 2: Monitor the Public API (OIDC Discovery Endpoint)

The OIDC discovery document at /.well-known/openid-configuration is the most critical Hydra endpoint. Every OAuth2 client and OIDC-aware library hits this endpoint on startup to discover token, authorization, and JWKS URLs. If it returns an error, clients cannot initialize.

  1. Log in to vigilmon.online and go to Monitors → New Monitor
  2. Choose HTTP / HTTPS
  3. Set the URL to: https://hydra.example.com/.well-known/openid-configuration
  4. Set the check interval to 1 minute
  5. Under Expected response, configure:
    • Status code: 200
    • Response body contains: "issuer"
    • Response time threshold: 1000ms
  6. Set the monitor name: [hydra-public] oidc-discovery
  7. Assign your primary alert channel
  8. Save

This monitors the full public API stack including TLS, ingress routing, and Hydra's database connectivity (the discovery document is dynamically generated from stored configuration).

Step 3: Monitor the Public Health Endpoint

Hydra exposes /health/alive and /health/ready on the public port:

curl -i https://hydra.example.com/health/ready
# HTTP/1.1 200 OK
# {"status":"ok"}

curl -i https://hydra.example.com/health/alive
# HTTP/1.1 200 OK
# {"status":"ok"}

The /health/ready endpoint specifically checks database connectivity — it returns 503 if Hydra cannot reach its database. This is the most actionable monitor for database issues.

Configure a Vigilmon monitor:

  1. URL: https://hydra.example.com/health/ready
  2. Interval: 1 minute
  3. Expected status: 200
  4. Response body contains: "ok"
  5. Monitor name: [hydra-public] /health/ready

| Endpoint | What It Checks | |---|---| | /health/alive | Process is running (liveness only) | | /health/ready | Process + database connectivity (readiness) | | /.well-known/openid-configuration | Full public API stack |

Run all three as separate monitors — the distinction between liveness and readiness failures tells you immediately whether it is a process issue or a database issue.

Step 4: Monitor the JWKS Endpoint

The JSON Web Key Set endpoint (/.well-known/jwks.json) serves the public keys that your API services use to validate JWTs locally without calling Hydra on every request. If this endpoint goes down and services have not cached the keys, JWT validation fails for all incoming requests.

curl -i https://hydra.example.com/.well-known/jwks.json
# HTTP/1.1 200 OK
# {"keys":[{"kty":"RSA","use":"sig",...}]}

Add a Vigilmon monitor:

  1. URL: https://hydra.example.com/.well-known/jwks.json
  2. Interval: 5 minutes (JWKS documents are stable; less frequent is appropriate)
  3. Expected status: 200
  4. Response body contains: "keys"
  5. Monitor name: [hydra-public] /jwks.json

After a key rotation event, verify the JWKS endpoint returns new keys before marking the rotation complete. A Vigilmon history report confirms exactly when the key set changed.

Step 5: Monitor the Admin API Health

The admin API runs on a separate port (4445 by default) and should never be internet-facing. Monitor it from your internal network using Vigilmon's agent or a private endpoint:

# From internal network
curl -i http://hydra.internal:4445/health/ready
# {"status":"ok"}

If your Vigilmon setup cannot reach internal addresses directly, add a thin proxy or expose the admin health endpoint through an authenticated internal load balancer:

# Nginx snippet: expose admin health on internal LB
location /admin-health {
    proxy_pass http://hydra.internal:4445/health/ready;
    allow 10.0.0.0/8;
    deny all;
}

Then monitor https://internal-lb.example.com/admin-health with:

  • Expected status: 200
  • Monitor name: [hydra-admin] /health/ready

Step 6: Monitor Token Introspection

The token introspection endpoint (/oauth2/introspect) is what your API gateways call to validate access tokens at runtime. Probe it with a known-invalid token to verify the endpoint is responding:

curl -i -X POST https://hydra.example.com/oauth2/introspect \
  -d "token=invalid_probe_token"
# HTTP/1.1 200 OK
# {"active":false}

An active: false response to an invalid token is the correct, healthy response — it confirms introspection is working. A 503 or network error means the endpoint is down.

Configure a Vigilmon HTTP monitor with POST method:

  1. URL: https://hydra.example.com/oauth2/introspect
  2. Method: POST
  3. Request body: token=vigilmon_probe
  4. Content-Type header: application/x-www-form-urlencoded
  5. Expected status: 200
  6. Response body contains: "active":false
  7. Monitor name: [hydra-public] introspection

This is the closest thing to an end-to-end auth flow test Vigilmon can run without a full OAuth2 client credential dance.

Step 7: Configure Alert Routing and Escalation

Hydra failures are authentication-layer P1 incidents. Configure tiered alerting:

| Monitor | Severity | Alert Channel | |---|---|---| | /health/ready (public) | P1 | PagerDuty + Slack immediately | | OIDC discovery | P1 | PagerDuty + Slack immediately | | JWKS endpoint | P2 | Slack + email | | Admin health | P2 | Slack + email | | Introspection endpoint | P1 | PagerDuty + Slack immediately |

Set the confirmation window to 2 checks for P1 monitors — confirmed outage within 2 minutes, no false pages from transient blips.

For the JWKS monitor, set the response time alert threshold to 2000ms — a slow JWKS response may indicate database pressure before it becomes an outage.

Step 8: Create a Hydra Status Page

Consolidate all Hydra monitors into a single internal status page:

  1. Go to Status Pages → New Status Page
  2. Name it: Hydra — Auth Infrastructure
  3. Create a group: Public API
    • Add /health/ready, OIDC discovery, JWKS, introspection monitors
  4. Create a group: Admin API
    • Add admin /health/ready monitor
  5. Set visibility to Internal (share with engineering and security teams)

This gives your team an immediate at-a-glance view during auth incidents, distinguishing public API failures from admin API failures and helping route the incident to the right responders.

Summary

Ory Hydra is a critical single point of failure for your entire token-based authentication layer. Vigilmon provides layered coverage:

| Monitor | What It Catches | |---|---| | /health/ready (public) | Process + database connectivity | | OIDC discovery endpoint | Full public API stack, TLS, routing | | JWKS endpoint | Key availability for JWT validation | | Admin /health/ready | Admin API layer, admin database access | | Token introspection | End-to-end introspection flow |

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

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