Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Deployment and Operations

Monitoring, Events and Metrics

Monitor Keycloak in production: login and admin events, event listeners, Prometheus metrics, health endpoints, logging, brute force detection and useful alerts.

An identity server that nobody watches fails in two ways: loudly (nobody can log in) and quietly (someone is guessing passwords). Keycloak gives you three observation tools: events (what users and admins did), metrics and health endpoints (how the server is doing), and logs. Combine them so you notice problems before your users report them.

Keycloak does not run on this site. Endpoint paths and option names refer to recent versions. The TryIt blocks are JavaScript stand-ins that analyze sample event and metrics text, similar to what a small monitoring script would do.

Events

Keycloak records two event streams, configured under Realm settings > Events:

  • User events: LOGIN, LOGIN_ERROR, LOGOUT, REGISTER, UPDATE_PASSWORD, REFRESH_TOKEN, CODE_TO_TOKEN, and many more, each with realm, client, user, IP address, and details.
  • Admin events: who changed what in the admin console or Admin API (create, update, delete operations with representation optional).

By default users events are not stored in the database. On the User events settings tab, enable Save events, choose which event types to save, and set an expiration so the table does not grow forever. On Admin events settings, enable Save events and optionally Include representation (stores the changed JSON, which is useful but may include sensitive data).

Event listeners receive events as they happen. The built-in ones are jboss-logging (writes events to the server log) and email (notifies users). Add a custom listener SPI to send events to Kafka, a webhook, or a SIEM (see the SPI lesson). Browse stored events in the console under Events, or query them via the Admin API.

Reading events for security signals

Interesting patterns:

  • Many LOGIN_ERROR events for one user from many IPs (password spraying or credential stuffing).
  • LOGIN_ERROR with invalid_user_credentials for many different usernames from one IP.
  • UPDATE_PASSWORD or UPDATE_EMAIL shortly after a login from an unusual IP.
  • Admin events adding roles to unusual users.
JS Stand-in: detect suspicious login failures

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Brute force protection

Under Realm settings > Security defenses > Brute force detection, enable temporary or permanent lockout after N failures, with a wait increment, maximum wait, and a failure reset window. Temporary lockout is the better default: permanent lockout lets attackers lock out real users (a denial of service). Pair it with MFA and strong password policies.

Health endpoints

Enable them at build time with --health-enabled=true. They are served on the management interface (port 9000 by default in recent versions):

  • /health/live: the process is up.
  • /health/ready: the server can handle requests (database connected).
  • /health: both.

Use ready for load balancer and Kubernetes readiness probes, and live for liveness probes. A failing readiness probe removes the node from rotation without restarting it.

Metrics

Enable with --metrics-enabled=true. The /metrics endpoint on the management port returns Prometheus text format. Useful series include JVM memory and garbage collection, HTTP request counts and durations, database pool usage, and cache statistics. Keycloak can also expose user event metrics when --event-metrics-user-enabled=true is set (check availability in your version), such as counts of logins and failures per realm.

TEXT
# HELP jvm_memory_used_bytes The amount of used memory
jvm_memory_used_bytes{area="heap"} 5.2428800E8
http_server_requests_seconds_count{method="POST",status="200",uri="/realms/{realm}/protocol/openid-connect/token"} 18342
http_server_requests_seconds_count{method="POST",status="401",uri="/realms/{realm}/protocol/openid-connect/token"} 311

The sample above is illustrative: metric names vary by version and enabled options.

Parsing Prometheus text is straightforward. This stand-in computes an error rate from lines like those:

JS Stand-in: compute an error rate from Prometheus text

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Logging

  • Default log level is INFO. Raise a single category when debugging, for example --log-level=INFO,org.keycloak.events:debug.
  • Send logs to stdout in JSON (--log-console-output=json) in containers and ship them to a central system.
  • Correlate by the request or session ID that Keycloak includes in events.
  • Remove debug levels afterwards; very verbose logs can leak sensitive details and slow the server.

Useful alerts

Signal Why
/health/ready failing on a node Node cannot serve requests
Rising 5xx rate on token endpoint Server or database trouble
Database pool near maximum Logins will queue
Login failure rate spike Attack, outage of an upstream IdP, or a misconfigured client
Cluster size drops Node crashed or network split
Heap usage and GC pauses Memory pressure
Certificate expiry within 14 days Prevent outage

Dashboards

Build one dashboard per question: Is it up? (health, request rate, latency percentiles.) Is it safe? (failed logins, lockouts, admin changes.) Is it healthy? (JVM, DB, cache.) The Keycloak documentation and community projects publish Grafana dashboards you can import and adapt.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which Keycloak feature records who changed realm configuration?

    Admin events log create, update, and delete operations performed through the admin console or API.
  2. 2. Which endpoint should a load balancer use to decide whether a node can take traffic?

    Readiness includes dependencies such as the database connection.
  3. 3. Why is temporary lockout usually preferable to permanent lockout?

    An attacker can deliberately fail logins to lock accounts forever; temporary lockouts limit the damage.
  4. 4. What is the risk of saving admin event representations?

    Representations contain the changed JSON, which may include sensitive fields.

Summary

  • Events show user and admin activity; configure saving and expiration deliberately.
  • Brute force detection should use temporary lockouts with MFA.
  • Health endpoints serve probes; metrics feed Prometheus and Grafana.
  • Keep management endpoints private, ship logs centrally, and alert on failure and latency.

Next: Backup, Export and Upgrades