tutorial

Monitoring Keycloak with Vigilmon: Health Endpoints, Realm Availability, SSL Certificates & Admin API Uptime

How to monitor Keycloak identity and SSO with Vigilmon — health endpoint checks, realm availability, SSL certificate monitoring, and admin REST API uptime.

Keycloak is the identity backbone for many organizations — handling SSO, OAuth2, OpenID Connect, and SAML for dozens of applications. When Keycloak goes down, every application that delegates authentication to it stops working for users. A login failure during peak hours can lock out an entire organization in seconds. Vigilmon gives you external visibility into Keycloak's health so you catch failures before users do: the built-in health endpoints, per-realm availability, SSL certificate expiry, and admin REST API uptime.

What You'll Build

  • A monitor on Keycloak's /health/ready health endpoint
  • Per-realm availability checks using the OIDC discovery endpoint
  • SSL certificate monitoring for your Keycloak domain
  • Admin REST API uptime monitoring
  • An alerting setup that distinguishes server-level failures from realm-level issues

Prerequisites

  • A running Keycloak 17+ instance (Quarkus distribution) with at least one realm configured
  • A Keycloak domain accessible over HTTPS (e.g., https://auth.example.com)
  • A free account at vigilmon.online

Step 1: Verify Keycloak's Health Endpoints

Keycloak exposes health endpoints at /health, /health/ready, and /health/live since version 17 (Quarkus distribution). Verify they are enabled and responding:

curl https://auth.example.com/health/ready

A healthy Keycloak returns:

{
  "status": "UP",
  "checks": []
}

The /health/ready endpoint confirms Keycloak is fully initialized and ready to serve requests — not just that the process is running. It validates database connectivity, connection pool initialization, and realm loading. Use /health/ready as your primary monitor.

Enabling health endpoints: If the endpoint returns 404, add health-enabled=true to keycloak.conf, or set KC_HEALTH_ENABLED=true in your Docker environment variables.

Keycloak 16 and earlier (WildFly distribution): Use /auth/health or /auth/realms/master/.well-known/openid-configuration instead.

Step 2: Create a Vigilmon HTTP Monitor for Keycloak's Health Endpoint

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: https://auth.example.com/health/ready.
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds (Keycloak can be slow under load).
  5. Expected status: 200.
  6. Keyword: "UP" (matches the status field in the JSON response).
  7. Click Save.

This monitor catches:

  • Keycloak process crashes or OOM kills
  • Database connectivity failures (Keycloak marks itself not-ready when the DB is unreachable)
  • Deployment failures after upgrades
  • JVM startup and initialization failures

Alert sensitivity: Set alerts to trigger after 1 consecutive failure. Unlike a website outage, a single Keycloak failure means authentication is broken for every connected application.

Step 3: Monitor Realm Availability via OIDC Discovery

Each Keycloak realm exposes an OpenID Connect discovery document at /.well-known/openid-configuration. This endpoint is served only when the realm is active and Keycloak's OIDC layer is functioning — making it a high-fidelity health check for the realm itself:

curl https://auth.example.com/realms/your-realm/.well-known/openid-configuration

A healthy realm returns a JSON document containing token endpoints, JWKS URIs, and supported scopes. Add a Vigilmon monitor for each realm:

  1. Add Monitor → HTTP.
  2. URL: https://auth.example.com/realms/your-realm/.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: Keycloak realm: your-realm.
  7. Repeat for every realm you operate.

When the global health monitor is green but a realm monitor fires, you have a realm-level issue (disabled realm, corrupted configuration, database schema mismatch) rather than a server-level problem. This layered approach dramatically speeds up diagnosis during incidents.

Step 4: Monitor SSL Certificates

Keycloak handles authentication, so a certificate expiry is catastrophic — all OAuth2 clients will immediately start rejecting the server's tokens and JWKS. Add SSL monitoring with generous advance warning:

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

If you use Keycloak to protect multiple subdomains, add a separate SSL monitor for each. A 30-day warning gives you adequate time to renew certificates before authentication breaks for all connected applications. Certificate errors in Keycloak manifest in hard-to-debug ways — OAuth2 clients log PKIX path building failed rather than "certificate expired."

Step 5: Monitor the Keycloak Admin REST API

The Keycloak Admin REST API (/admin/realms) powers realm management, user federation, and client configuration. A degraded admin API may not affect end-user logins immediately, but it blocks operational work and is an early indicator of backend problems:

curl https://auth.example.com/admin/realms
# Returns 401 Unauthorized when the API is up

An unauthenticated request returns 401 Unauthorized — which proves the admin API is up and routing correctly. Add this monitor:

  1. Add Monitor → HTTP.
  2. URL: https://auth.example.com/admin/realms.
  3. Check interval: 5 minutes.
  4. Expected status: 401 (unauthenticated requests confirm the endpoint is alive).
  5. Label: Keycloak Admin API.
  6. Click Save.

A 401 response is a valid health signal here. If the admin API is truly down, you'll get a connection error, 503, or 404 — not a 401.

Step 6: End-to-End Token Endpoint Check

The most complete Keycloak check is hitting the token endpoint directly — this exercises the full authentication stack including the realm database, caches, and OIDC layer:

curl -X POST https://auth.example.com/realms/your-realm/protocol/openid-connect/token \
  -d "grant_type=client_credentials" \
  -d "client_id=monitoring-client" \
  -d "client_secret=your-client-secret"

Set up a dedicated monitoring-client in Keycloak with the Client Credentials grant enabled and no other permissions. A successful auth returns an access_token in the JSON response:

  1. Add Monitor → HTTP (POST).
  2. URL: https://auth.example.com/realms/your-realm/protocol/openid-connect/token.
  3. Method: POST.
  4. Body: grant_type=client_credentials&client_id=monitoring-client&client_secret=your-secret.
  5. Expected status: 200.
  6. Keyword: access_token.
  7. Check interval: 5 minutes.
  8. Label: Keycloak token issuance.

This is the gold-standard end-to-end Keycloak check — if it fires, users cannot authenticate.

Step 7: Configure Alerting

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

| Monitor | Trigger | Action | |---|---|---| | /health/ready | Non-200 or UP missing | Check journalctl -u keycloak; verify DB connectivity | | Realm OIDC discovery | Non-200 or keyword missing | Check if realm is disabled; inspect Keycloak logs | | SSL certificate | < 30 days to expiry | Renew certificate; check ACME automation | | Admin REST API | Non-401/200 | Admin API degraded; check Keycloak node health | | Token endpoint | Non-200 or no access_token | Full auth stack failure; escalate immediately |

Alert after: 1 consecutive failure for all Keycloak monitors — Keycloak failures cause immediate, widespread application impact.

Common Keycloak Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Keycloak JVM crash / OOM | /health/ready unreachable; alert within 60 s | | Database goes down | /health/ready returns non-ready; alert within 60 s | | Realm accidentally disabled | Realm OIDC discovery returns 404; global health stays green | | SSL certificate expires | SSL monitor alerts at 30-day threshold | | Upgrade breaks realm config | Realm OIDC discovery fails; global health may be green | | Admin API degraded | Admin API monitor fires; end-user logins may still work | | Full auth stack failure | Token endpoint monitor fires; no users can authenticate | | DNS misconfiguration | All monitors fire simultaneously |

Keycloak is the single point of failure for authentication in many architectures. When it goes down, every application behind it stops working — login pages fail, API tokens can't be issued, and users are locked out. Vigilmon gives you layered external monitoring of Keycloak's health endpoints, realm availability, certificates, and the full authentication stack so you're alerted in seconds rather than hearing about it from frustrated users.

Start monitoring Keycloak 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