Keycloak Plugin

The Keycloak plugin registers Keycloak realm and runtime state as a Konduo resource. It is a resource plugin for Keycloak operations and read-only directory evidence, not a Konduo authentication provider.

Highlights

• Provides issuer discovery, Admin API readiness, inventory summary, and read-only user/group views.
• Connects HTTP, JVM, DB pool, cache, worker pool, session, and password hashing signals through a Prometheus mapping pack.
• Separates token endpoint and client-session statistics for session pressure diagnostics.
• Separates diagnostics for discovery, Admin API, metrics, and historical evidence.
• Reads recent LOGIN_ERROR events as bounded evidence with masked identifiers.
• Summarizes external IdP alias, provider, enabled state, sync mode, and broker flow as read-only readiness.
• Summarizes realm key metadata and certificate expiry as safe rotation hints.
• Shows a realm security settings snapshot and simple differences from an explicitly selected expected profile.
• Alert rules cover JVM pressure, DB waits, worker saturation, cache efficiency, and scrape evidence.

Before Registration

• Prepare issuer URL, Admin API service account client id/secret, and read-only realm-management roles.
• Use least-privilege roles such as view-realm, view-users, and query-users for directory views.
• Check clients, events, identity providers, keys, and sessions read permissions when optional diagnostics are enabled.
• Metric dashboards require label filters that select the Keycloak scrape target.

Operations Tips

• This plugin does not change Konduo login behavior.
• Directory users and groups are normalized response rows, not persisted Konduo identities.
• Treat generic availability as Core health/probe state and metric rules as Keycloak-domain risk signals.

Operator Views

• Realm overview confirms issuer discovery, token endpoints, Admin API readiness, and realm metadata.
• Inventory summary shows realm, client, user, and group scale without exposing client secrets.
• Users and groups views provide read-only directory evidence for account presence and group composition.
• Dashboards show HTTP requests, JVM, DB pool, cache, worker pool, sessions, and password-hashing metrics.
• Diagnostics separate discovery, Admin API, credential/permission, metric coverage, and runtime pressure.
• Session pressure diagnostics keep metric-source readiness visible even when Admin API session permissions are missing.
• Failed login evidence provides reason summaries and bounded event rows; spike detection and correlation are outside CE scope.
• External IdP diagnostics do not show secret/certificate config values and do not perform real external login tests.
• Key rotation diagnostics do not show certificate bodies, public/private keys, or secret material.
• Security drift is not risk scoring, security grading, or compliance evaluation; those are outside the CE scope.

Diagnostics And Alerts

• Alert rules focus on JVM memory, DB connection waits, worker saturation, cache hit ratio, HTTP errors/latency, and scrape evidence.
• Issuer discovery can succeed while Admin API permissions are insufficient, leaving directory views and some diagnostics partial.
• Admin API diagnostics classify realm/users/groups/clients/events/IdP/keys/sessions permissions as separate rows.
• Keycloak metric labels can mix deployment, realm, and client dimensions, so confirm label filters select the intended realm/runtime.
• Directory evidence is for operations and is not the authoritative source for Konduo users, roles, or RBAC.

Management Boundary

• User create/delete, password reset, role mapping, and client/realm configuration changes are outside CE plugin scope.
• Security drift is a neutral snapshot/diff helper and should not be treated as an audit report or compliance decision.
• Use read-only, least-privilege Admin API credentials whenever possible.
• The plugin observes Keycloak state but does not change Konduo authentication mode or session policy.
• Client secrets and tokens stay inside the secret boundary and must not appear in diagnostics.

Example Workflows

• For login incidents, inspect issuer discovery, Admin API readiness, HTTP error/latency, DB pool waits, and worker saturation together.
• If a user is missing, check service-account roles, realm, user-search permissions, and pagination/filter conditions.
• For low cache efficiency, compare cache hit/miss, cluster node state, JVM memory, and recent realm/client changes.
• For password-hashing pressure, combine login traffic, worker pool, and CPU/JVM pressure.

---

Keycloak Enterprise Overlay

The Keycloak Enterprise overlay adds MCP descriptors, anomaly rules, Admin API diagnostics, and metric mapping to Keycloak resource monitoring. Login is handled by the separate auth-oidc provider; the Keycloak plugin focuses on realm operations and diagnostics.

Highlights

• Provides dashboard templates, monitoring overview, diagnostics, inventory/session/failed-login/IdP/key/security evidence, metrics mapping, and alert/anomaly rule catalogs through MCP.
• Surfaces Admin API discovery, realm state, JVM, DB pool, worker, cache, and authentication traffic pressure as diagnostic evidence.
• Adds Enterprise failed-login spike correlation and weighted security drift risk assessment on top of CE read-only evidence.
• Prometheus mapping packs connect Keycloak logical metrics to concrete metric names.
• Related instance templates help create an auth-oidc provider from a monitored Keycloak realm.

Before Registration

• Prepare Keycloak base URL, realm, Admin API permissions, and metric endpoint exposure.
• If login integration is needed, register an auth-oidc provider client separately from the Keycloak resource.
• Keep Admin API service account credentials separate from login client credentials.

Operations Tips

• Do not use Keycloak directory/Admin API routes as the login processing path.
• Anomaly rules need metric-source linkage to evaluate meaningful signals.
• Troubleshoot OIDC login failures separately from Keycloak resource diagnostics failures.

Operational Scenarios

• When login latency or failure rate rises, inspect realm state, worker saturation, DB pool pressure, cache churn, and authentication traffic pressure together.
• Use failed-login correlation to compare bounded LOGIN_ERROR evidence with optional baselines before escalating an incident.
• Use security-risk assessment to review weighted realm setting drift with identity policy owners; it is an operational review aid, not a legal compliance attestation.
• If Keycloak also authenticates Konduo users, create an auth-oidc instance from the related instance template and keep credentials separated.
• MCP diagnostics expose realm operating state and metric mapping readiness as read-only context for incident-analysis agents.

Boundaries

• The Keycloak resource plugin owns realm operations and diagnostics; the auth-oidc auth plugin owns Konduo login processing.
• Admin API credentials are for resource diagnostics only and must not be mixed with login client secrets.
• MCP descriptors remain read-oriented and do not expose directory mutation, secret material, or Keycloak configuration changes.