Keycloak Realm Setup

Create the realm, clients, and login user the platform needs before you install — with the commands to do it by hand.

Before you run Platform Installation, a Keycloak realm has to exist with three clients and a login user already in it. The operator only provisions into an existing realm (see Managed Keycloak) — it never creates the realm itself, so this is a one-time manual step.

One realm, shared by the platform and every validator

Everything below goes into one realm. That's the same realm you point the operator at with operator.keycloak.realm in Platform Installation, and the same realm Managed Keycloak later provisions per-validator clients into. There's no separate "platform realm" and "validator realm" — one realm serves both.

Placeholders used below

Placeholder	Example	Is
$REALM	validator-intellecteu-devnet	The realm you create — becomes operator.keycloak.realm.
$BASE_HOSTNAME	validators.example.com	Should match operatorRuntime.baseHostname — used in the UI client's redirect URI.
$UI_USERNAME / $UI_EMAIL	catalyx-ui-admin / [e-mail]	The browser login user you create for catalyx-canton-ui.

Pick your own values — don't reuse the examples above, and don't leave any password as a placeholder like admin in anything beyond a local minikube run.

What to create

Object	Realm	Configuration
Realm	—	$REALM, enabled, display name "CatalyX Canton Validator" (or your own).
Client — catalyx-operator-admin	$REALM	Confidential, service accounts enabled, standard flow disabled (service account only — never used for browser login). Its secret is what you store as admin-client-secret in the catalyx-operator-keycloak secret in Platform Installation, and is referenced by operator.keycloak.adminClientId.
Client — catalyx-api	$REALM	Confidential, service accounts enabled, standard flow enabled, direct access grants disabled, redirectUris: ["/*"], webOrigins: ["/*"]. Its secret is what you store as client-secret in the catalyx-api-credentials secret.
Client — catalyx-canton-ui	$REALM	Public, standard flow enabled (browser OIDC with PKCE), direct access grants disabled, redirect URI https://$BASE_HOSTNAME/*, web origin https://$BASE_HOSTNAME. Matches ui.oidc.clientId (default catalyx-canton-ui).
User — $UI_USERNAME	$REALM	Enabled, email verified, password set. Used to sign in to the CatalyX UI in a browser via catalyx-canton-ui. Carries no realm roles — it's a plain login, not an admin account.

Permission to grant

There is one role assignment to make: the catalyx-operator-admin service account (service-account-catalyx-operator-admin) gets the realm-admin client role of $REALM's own realm-management client — not master's. That scopes the operator to administering just $REALM, and is what lets its client-credentials login create and update the per-validator clients, scopes, and users described in Managed Keycloak.

Commands

Everything below can equally be done by hand in the Keycloak Admin Console (Realm settings → Create realm, Clients → Create client, Users → Add user, and the role assignment under a user's Role mapping tab).

Run these with kcadm.sh against your Keycloak — from a shell with kcadm.sh on the path (for example kubectl exec into the Keycloak pod), or adapt them to the Admin REST API if you're not using the CLI.

1

Authenticate

kcadm.sh config credentials \
  --server "$KEYCLOAK_URL" \
  --realm master \
  --user admin \
  --password <admin-password>

2

Create the realm

kcadm.sh create realms \
  -s realm="$REALM" \
  -s enabled=true \
  -s displayName="CatalyX Canton Validator"

3

Create catalyx-operator-admin in $REALM and grant it realm-admin

kcadm.sh create clients -r "$REALM" \
  -s clientId=catalyx-operator-admin \
  -s enabled=true \
  -s publicClient=false \
  -s serviceAccountsEnabled=true \
  -s standardFlowEnabled=false

kcadm.sh add-roles -r "$REALM" \
  --uusername service-account-catalyx-operator-admin \
  --cclientid realm-management \
  --rolename realm-admin

4

Create catalyx-api in $REALM

kcadm.sh create clients -r "$REALM" \
  -s clientId=catalyx-api \
  -s enabled=true \
  -s publicClient=false \
  -s serviceAccountsEnabled=true \
  -s standardFlowEnabled=true \
  -s directAccessGrantsEnabled=false \
  -s 'redirectUris=["/*"]' \
  -s 'webOrigins=["/*"]'

5

Create catalyx-canton-ui in $REALM

kcadm.sh create clients -r "$REALM" \
  -s clientId=catalyx-canton-ui \
  -s enabled=true \
  -s publicClient=true \
  -s serviceAccountsEnabled=false \
  -s standardFlowEnabled=true \
  -s directAccessGrantsEnabled=false \
  -s "redirectUris=[\"https://$BASE_HOSTNAME/*\"]" \
  -s "webOrigins=[\"https://$BASE_HOSTNAME\"]"

6

Create the UI login user

kcadm.sh create users -r "$REALM" \
  -s username="$UI_USERNAME" \
  -s email="$UI_EMAIL" \
  -s enabled=true \
  -s emailVerified=true

kcadm.sh set-password -r "$REALM" \
  --username "$UI_USERNAME" \
  --new-password <choose-a-password>

7

Retrieve the catalyx-operator-admin secret

CLIENT_ID=$(kcadm.sh get clients -r "$REALM" \
  -q clientId=catalyx-operator-admin --fields id --format csv --noquotes)
kcadm.sh get "clients/$CLIENT_ID/client-secret" -r "$REALM"

Store the printed value as admin-client-secret in the catalyx-operator-keycloak secret — see step 2 of Platform Installation.

8

Retrieve the catalyx-api secret

CLIENT_ID=$(kcadm.sh get clients -r "$REALM" \
  -q clientId=catalyx-api --fields id --format csv --noquotes)
kcadm.sh get "clients/$CLIENT_ID/client-secret" -r "$REALM"

Store the printed value as client-secret in the catalyx-api-credentials secret — also step 2 of Platform Installation.

---

Next step

With the realm, its three clients, and the UI login user in place, continue to Platform Installation to create the Kubernetes secrets from the two client secrets above and install the Helm chart.