How to Monitor Your Keycloak Identity Server with Vigilmon

Keycloak is the most widely deployed open-source identity and access management server. It handles authentication, authorization, SSO, and OIDC for enterprise applications. When Keycloak goes down, users cannot log in — and that's always a P0 incident.

This guide shows how to monitor Keycloak with Vigilmon.

Keycloak Health Endpoints

Keycloak 22+ exposes dedicated health endpoints:

# Liveness probe
curl http://localhost:8080/health/live
# {"status":"UP","checks":[]}

# Readiness probe (verifies DB connection)
curl http://localhost:8080/health/ready
# {"status":"UP","checks":[{"name":"Keycloak database connections","status":"UP"}]}

OIDC Discovery Endpoint

The most critical endpoint to monitor is the OIDC discovery URL:

GET https://keycloak.your-domain.com/realms/{realm}/.well-known/openid-configuration

If this is down, your applications cannot authenticate users.

Add Monitors in Vigilmon

Monitor 1: Keycloak Health

• URL: https://keycloak.your-domain.com/health/ready
• Expected status: 200
• Check interval: 1 minute

Monitor 2: OIDC Discovery

• URL: https://keycloak.your-domain.com/realms/your-realm/.well-known/openid-configuration
• Expected status: 200
• Expected body contains: issuer
• Check interval: 1 minute

Application Auth Health Route

Node.js / Express:

const jwksClient = require("jwks-rsa");

const client = jwksClient({
  jwksUri: `https://${process.env.KEYCLOAK_HOST}/realms/${process.env.KEYCLOAK_REALM}/protocol/openid-connect/certs`,
});

app.get("/health/auth", async (req, res) => {
  try {
    const keys = await client.getSigningKeys();
    res.json({ status: "ok", keycloak: "reachable", signingKeys: keys.length });
  } catch (err) {
    res.status(503).json({ status: "error", keycloak: "unreachable", message: err.message });
  }
});

Spring Boot:

@GetMapping("/health/auth")
public ResponseEntity<Map<String, Object>> authHealth() {
    try {
        restTemplate.getForObject(jwkSetUri, String.class);
        return ResponseEntity.ok(Map.of("status", "ok", "keycloak", "reachable"));
    } catch (Exception e) {
        return ResponseEntity.status(503).body(Map.of(
            "status", "error",
            "keycloak", "unreachable"
        ));
    }
}

Docker Compose with Health Checks

version: "3.8"
services:
  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start-dev
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
      KC_DB: postgres
      KC_HEALTH_ENABLED: "true"
    ports:
      - "8080:8080"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health/ready"]
      interval: 30s
      timeout: 10s
      retries: 10
      start_period: 60s
    restart: unless-stopped

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: keycloak
spec:
  template:
    spec:
      containers:
        - name: keycloak
          image: quay.io/keycloak/keycloak:24.0
          livenessProbe:
            httpGet:
              path: /health/live
              port: 8080
            initialDelaySeconds: 60
            periodSeconds: 30
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8080
            initialDelaySeconds: 60
            periodSeconds: 10

What to Monitor

Monitor	Endpoint	Priority
Keycloak readiness	/health/ready	Critical
OIDC discovery	/.well-known/openid-configuration	Critical
App auth health	/health/auth	High
SSL certificate	Keycloak domain	High

Alert Configuration

Authentication failures are P0:

• 0-grace-period alerts — alert on first failed check
• Multi-region monitoring — Vigilmon checks from multiple regions
• On-call escalation — Slack + PagerDuty

Keycloak is the front door to your application. Monitor it externally and catch issues before users do.

---

Vigilmon — free uptime monitoring for Keycloak, Auth0, and any authentication service.