keycloak

Keycloak: an application controller type, version 1. A controller of this type is written under controllers.application with type: keycloak.

Its connectivity test identifies the system it reaches by keycloak@<host>:<port>, from the base URL, so that a second controller for the same system is warned of.

Connection

In the controller’s connection:

• url (string, required): Keycloak’s base URL as the site’s orchestrators reach it, [https://host[:port]](https://host[:port]), with its http-relative-path if it has one. HTTPS only
• management_port (int, default 9000): the port of Keycloak’s management interface on the same host (http-management-port), which serves /health/ready under the base URL’s path: start Keycloak with health-enabled=true
• server_certificate_sha256 (string): the SHA-256 fingerprint of the certificate Keycloak presents, pinned at registration: the connectivity test shows it until it is set. The management interface must present it too, unless it has a certificate of its own
• next_server_certificate_sha256 (string): the SHA-256 fingerprint of the certificate that will replace the pinned one, trusted as it is: pin it before Keycloak changes certificates, so the change leaves no gap
• management_certificate_sha256 (string): only when the management interface has a certificate of its own (https-management-certificate-file): its SHA-256 fingerprint. Unset, it must present Keycloak’s
• next_management_certificate_sha256 (string): the certificate that will replace the management interface’s own, trusted as it is
• connect_timeout (duration, default 10s): how long connecting and the TLS handshake may take; each call is bounded by its own deadline

Auth methods

The controller’s auth.method is one of these. A field marked secret comes only from the secret auth.credentials_ref names; the others are set in auth.config, or in that secret.

none

No probe user: realm.health reads Keycloak’s readiness alone, which stays up while its database refuses writes (ADR 0014 §2).

No fields: no credentials_ref.

basic

The probe user, which signs in to each realm a binding names and out again: a user with no roles beyond the realm’s defaults, signing in through a public client that allows direct sign-in only. A sign-in writes a session, so it fails while Keycloak’s database refuses writes.

• username (string, required): the probe user, a user of each realm a binding names, e.g. qfence-probe
• probe_client (string, default qfence-probe): the public client it signs in through, with direct access grants on and every other flow off
• password (string, required, secret)

oauth2_client_credentials

The admin account: realms.list’s own credentials, never the controller’s. A confidential client in the master realm whose service account holds read-only roles only (view-realm or query-realms on each realm’s client there). It lists the realms, so a binding’s realm is chosen rather than typed.

• client_id (string, required): the client in the master realm, e.g. qfence-admin
• client_secret (string, required, secret)

Capabilities

The controller enables each it uses in its capabilities list.

realm.health

HEALTHY when the management interface reports Keycloak ready and, with a probe user, that user signs in to the realm and out again within probe_timeout. UNHEALTHY when readiness is DOWN, a sign-in fails on the server or the realm does not exist, or Keycloak is not running (the pinned host refuses the connection). UNKNOWN when Keycloak does not answer in time, or refuses the probe user’s credentials: they say nothing about Keycloak, and a rotated password must never fail a plan over.

Category: observation; bound as health; resource realm.

Per binding, in its params:

• probe_timeout (duration, default 15s): how long the probe user’s sign-in and sign-out may take, at most 20s: longer than the 10 s Keycloak takes to fail a sign-in on a database that refuses writes, so that reads UNHEALTHY rather than UNKNOWN

Validation checks: tls.pinned, health.enabled, ready.database, probe.signin.

realms.list

The realms the admin account may view, by name. It needs the admin account as its own credentials; without it, a binding’s realm is typed.

Category: discovery; resource realm.

Advertised once its setup is done: auth.

It takes a credential of its own, in its entry’s auth, by oauth2_client_credentials.

Validation checks: tls.pinned, admin.readonly.

Addresses

Every address the type contacts. A secret’s scope (-scope-host) is checked against each that receives credentials.

• connection.url (port url, receives credentials): Keycloak’s base URL: the probe user’s password and the admin client’s secret go here
• connection.url (port connection.management_port): Keycloak’s management interface, on the base URL’s host: its health, asked with no credentials