Konduo Manual

English

한국어

English

한국어

Appearance

Keycloak Plugin ​

TLS settings location ​

TLS modes, CA/client certificates and keys, server names and verification options are grouped under Security > TLS. Endpoint/port fields keep their original location. Grouping does not change field keys, saved values, defaults, sensitive handling, visibility or validation.

Basic accessibility observation ​

Resource overviews show accessible, inaccessible, or access unknown independently of metric sources. Successful access does not attest healthy membership, replication, partitions, or workloads; use domain diagnostics and alerts for those conditions. Existing liveness/readiness fields are domain evidence and do not drive the single core-owned access alarm. Unknown observations do not resolve firing incidents.

TLS ​

Enter a private CA in tls_ca_cert (PEM) to verify Keycloak discovery and admin endpoints. tls_server_name selects the certificate DNS name, and tls_client_cert with tls_client_key supplies mutual TLS credentials. tls_insecure_skip_verify retains encryption but bypasses server verification and defaults to false.

Chart value semantics ​

Target scrape status is shown as a state per Prometheus target, not as overall Keycloak health. Mixed target results remain conflicting observations. Cluster size is an integer with consistent observations; mapping v2 preserves disagreeing node values. Percent gauges have fixed 0–100 bounds.

Three traffic trends share one row. Identity, JVM, database, cache and worker details form a continuous grid of three or four charts per row instead of five separate two-chart sections. Existing saved layouts and query definitions remain unchanged.

Overview groups availability, CPU, heap and cluster size above traffic trends. Runtime and Dependencies separates identity, JVM, database, cache and worker comparisons into paired trend rows. All 17 panels and saved layouts remain available; missing optional metrics are not treated as healthy values.

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.
  • The resource target card shows the realm name from /realms/{realm} in the issuer URL, even when discovery is unreachable.
  • 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.
  • Heap usage is unavailable unless every selected heap pool has matching used/max series and a positive reported maximum. GC pause average is unavailable when no GC events occurred. Cluster size is shown as a node-count stat rather than a percentage gauge.
  • 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.

Opt-in Idle Process Shutdown ​

When the core's idle-stop policy is explicitly enabled, the Keycloak plugin can stop after all requests and core references are idle. It has no background jobs or retained query results. Preparation closes idle HTTP connections and blocks new health checks, queries, and actions; busy requests continue normally. An aborted preparation reopens admission. Metadata remains readable, and the next admitted request can start a fresh process. This does not stop the Keycloak service or delete saved resource settings. Default deployments keep the process running unless the operator enables this policy.

Keycloak Enterprise Overlay ​

TLS settings location ​

TLS modes, CA/client certificates and keys, server names and verification options are grouped under Security > TLS. Endpoint/port fields keep their original location. Grouping does not change field keys, saved values, defaults, sensitive handling, visibility or validation.

Basic accessibility observation ​

Resource overviews show accessible, inaccessible, or access unknown independently of metric sources. Successful access does not attest healthy membership, replication, partitions, or workloads; use domain diagnostics and alerts for those conditions. Existing liveness/readiness fields are domain evidence and do not drive the single core-owned access alarm. Unknown observations do not resolve firing incidents.

TLS ​

Enter a private CA in tls_ca_cert (PEM) to verify Keycloak discovery and admin endpoints. tls_server_name selects the certificate DNS name, and tls_client_cert with tls_client_key supplies mutual TLS credentials. tls_insecure_skip_verify retains encryption but bypasses server verification and defaults to false.

Chart value semantics ​

Target scrape status is shown as a state per Prometheus target, not as overall Keycloak health. Mixed target results remain conflicting observations. Cluster size is an integer with consistent observations; mapping v2 preserves disagreeing node values. Percent gauges have fixed 0–100 bounds.

Three traffic trends share one row. Identity, JVM, database, cache and worker details form a continuous grid of three or four charts per row instead of five separate two-chart sections. Existing saved layouts and query definitions remain unchanged.

Overview groups availability, CPU, heap and cluster size above traffic trends. Runtime and Dependencies separates identity, JVM, database, cache and worker comparisons into a continuous three- or four-column trend grid. All 17 panels and saved layouts remain available; missing optional metrics are not treated as healthy values.

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.

Metric interpretation ​

  • Heap usage is unavailable unless every selected heap pool has matching used/max series and a positive reported maximum. GC pause average is unavailable when no GC events occurred. Cluster size is shown as a node-count stat rather than a percentage gauge.

Highlights ​

  • The resource target card shows the realm from the issuer URL even when discovery is unavailable.
  • 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.

MCP diagnostic execution effects ​

The run_diagnostics tool changes diagnostic execution and cooldown state. Its descriptor declares operation_class: diagnostic_lifecycle; MCP advertises readOnlyHint=false, destructiveHint=false and idempotentHint=false. Diagnostic queries retain read-only hints. Both queries and actions continue to require mcp:invoke and the existing resource permissions/audit checks. Safety hints do not change authorization or guarantee safe retries.

MCP tool input contracts ​

Discovery and admin readiness diagnostics and static catalogs accept {}. Summary, metrics, and monitoring diagnostics declare metric_source_id; historical evidence also declares lookback. Existing filter aliases remain supported for metric selection. Optional correlation baseline and expected security profile inputs retain their existing bounds.

The advertised JSON Schema is checked before plugin dispatch. Omitted optional values retain plugin defaults. Arguments do not replace resource-instance authorization; stored connection credentials are supplied by Konduo. Open schemas are retained only for existing dynamic filters or aliases, and each advertised property describes its caller-facing meaning. Plugin result shapes can vary with product/version, available evidence, and partial failures; no stable outputSchema is promised for these dynamic responses. Client and resource coverage rules are defined in enterprise/backend/docs/plugin-contract.md in the Enterprise source repository.

Opt-in Idle Process Shutdown ​

When the core's idle-stop policy is explicitly enabled, the Keycloak plugin can stop after all requests and core references are idle. It has no background jobs or retained query results. Preparation closes idle HTTP connections and blocks new health checks, queries, and actions; busy requests continue normally. An aborted preparation reopens admission. Metadata remains readable, and the next admitted request can start a fresh process. This does not stop the Keycloak service or delete saved resource settings. Default deployments keep the process running unless the operator enables this policy.