Managed Keycloak

Let CAT-BM provision the OIDC clients, scopes, and users a validator needs.

With spec.auth.managedKeycloak: true, the operator provisions everything the validator's components need inside an existing Keycloak realm, on the validator's first reconcile.

Configuration

At the platform level, set the operator's Keycloak values at install time — see Platform Installation.

On the validator, the whole spec.auth block reduces to four fields:

spec:
  auth:
    managedKeycloak: true
    targetAudience: https://canton.network.global
    ledgerApiUserManagementScope: daml_ledger_api

spec.network.partyHint must also be set — it becomes the wallet user's username.

The realm must already exist, and the operator's admin client must exist inside that realm with realm-management permissions. The operator authenticates with the client credentials grant against the realm named in operator.keycloak.realm.

---

What gets created

For a validator named my-validator, in the realm you configured:

Object	Name	Notes
Public client — CNS UI	my-validator-cns-ui	Redirect URI and web origin derived from operatorRuntime.baseHostname. Gets an audience mapper for targetAudience.
Public client — Wallet UI	my-validator-wallet-ui	As above.
Public client — Wallet Gateway	my-validator-wallet-gateway	Created whether or not the Wallet Gateway is enabled. Gets an audience mapper, a hardcoded sub claim mapper, and a 30-minute access token lifespan. The profile and email default scopes are removed.
Confidential client — backend	my-validator-validator-backend	Service accounts enabled. Its generated secret is written to a Kubernetes Secret.
Client scope — Ledger API	the value of ledgerApiUserManagementScope	Created once per realm, with an audience mapper for targetAudience.
Client scope — per validator	my-validator-ledger-api	Attached as an optional scope to the platform's API client. Carries the audience, the user-management scope claim, and the backend service account's subject.
User — wallet	the value of spec.network.partyHint	Enabled, email verified, no password and no roles.

The generated secret

The operator writes an Opaque Kubernetes Secret in the validator's namespace:

Name	<validator-name>-managed-ledger-api-auth
Key	client-secret
Value	The generated secret of <validator-name>-validator-backend

This secret has no owner reference, so it is not deleted when the validator is deleted. That is deliberate — it lets you recreate a validator without re-provisioning — but it means you must remove it yourself when decommissioning permanently.

Checking the result

Provisioning results are recorded on the validator's status and shown on the UI's Identity tab.

kubectl -n <namespace> get validator my-validator -o jsonpath='{.status.managedAuth}' | jq

Status field	Meaning
provisioned	true once provisioning has completed successfully.
walletUiClientId, cnsUiClientId, walletGatewayClientId, ledgerApiClientId	The client IDs that were created.
ledgerApiClientSecretName, ledgerApiClientSecretKey	Where the backend client secret was written.
authUrl	The resolved OIDC issuer URL.
ledgerApiUser, walletUserName	Internal Keycloak user identifiers for the backend service account and the wallet user. These are IDs, not usernames.

Once provisioned is true, the operator stops contacting Keycloak on subsequent reconciles and reads all authentication configuration from status.managedAuth.

---

Things to know before you rely on it

Provisioning is idempotent, but not fully self-correcting. Clients that already exist have their redirect URIs and web origins overwritten to match the current operatorRuntime.baseHostname. Client scopes are not updated — a scope created with the wrong targetAudience must be corrected by hand in Keycloak.

Changing the base hostname rewrites redirect URIs. If you change operatorRuntime.baseHostname after validators exist, their public clients are updated on the next provisioning cycle.

The platform API client is optional but recommended. If the client named by operator.keycloak.apiClientId (default catalyx-api) does not exist in the realm, the operator logs a warning and continues — but the UI will not be able to perform Ledger API operations for that validator.

Nothing is cleaned up on delete. Clients, scopes, and users created for a validator remain in the realm after the validator is deleted.