Ctrlk
Support Center
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Validator Management with Integrated Keycloak

This page explains how to use Catalyst to create and deploy Validators on the Canton network with Integrated Keycloak. In this mode, Catalyst provisions and configures Keycloak automatically as part of the validator deployment, you don't need to bring or manage your own identity provider.

Keycloak is a login and user-management system: it verifies who you are, lets you sign in securely, and controls what you're allowed to access. When you create a validator with integrated Keycloak, Catalyst uses Keycloak as the security gate for all validator services, automatically creating the required users and connecting components such as the Wallet UI and APIs.

This guide is for the Default authentication option with integrated Keycloak. To set up a validator with a custom identity provider, see Create Validator with Custom Identity Provider.

Validator Management

Validators can be deployed on Catalyst and seamlessly connected to the Canton Network.

Set Up a Validator

To set up a Validator, go to the Validators tab and click the Set up validator button to open a side window.

1

Main Settings Configuration

Provide the following information:

  • Sponsor SV Name

  • Name

  • Onboard secret

  • Image tag

  • Image repo

  • Image pull secret

  • Scan address

  • SV sponsor address

  • Party hint

  • Migration id

More info about these fields
Field
Description

Sponsor SV Name

The name of the Super Validator that sponsored you to join the network

Name

The identifier or label for the validator node

Onboard secret

Passphrase obtained from the super validator in order to join the network

Image tag

The specific version or tag of the container image to be used

Image repo

The repository where the container image is stored

Image pull secret

Credentials required to pull the container image from a private registry (secret docker-registry)

Scan address

The address used for scanning and retrieving validator-related data

SV Sponsor Address

URL of the SV app of the super validator sponsoring you. Typically starts with https://sv.sv-N

Party hint

Used as a prefix for the Party ID of your validator's administrator. Format: <organization>-<function>-<enumerator>, e.g., myCompany-myWallet-1

Migration id

Used to track database migrations. Starts at 0 for the initial deployment and increments by 1 with each migration

An onboarding secret should be requested from your sponsoring SV in order to join the network.

Only turn on the Restore participant identities toggle if you want to restore a validator from an Identity Dump.

2

Cluster Configuration

Provide the following information:

2.1 — Enable or disable:

  • Disable wallet

  • Fail on app version mismatch

  • Disable probes

2.2 — Fill in the remaining fields:

  • Default JVM Options

  • Top up:

    • Enable

    • Min Top up interval

    • Target throughput

    • Contact point

More info about these fields
Field
Description

Disable wallet

Turn on to not deploy a wallet UI with your validator

Fail on app version mismatch

If enabled, the deployment will fail if there is a mismatch between the validator and network application versions

Disable probes

Probes test the health of a deployment. It is recommended to not disable them in standard scenarios

Default JVM Options

Default configuration options for the Java Virtual Machine (JVM) running the validator

Top up

Enables or disables the validator's automatic traffic purchase mechanism

Min Top up interval

Minimum amount of time that must pass between two automatic top-ups

Target throughput

Desired average traffic rate in bytes per second

Contact point

Where the validator can be reached for operational or administrative communication

Do not set the Custom Authentication flag on — these instructions are for integrated Keycloak configuration. To use a custom identity provider instead, see Create Validator with Custom Identity Provider.

3

Cluster Participant Configuration

Provide the following information:

  • Node Identifier

  • Enable or disable:

    • Expose Ledger API

    • Private JSON API

  • Default JVM Options

More info about these fields
Field
Description

Node identifier

A unique identifier for the validator node within the network

Expose ledger API

Opens up GRPC Ledger API to the outside

Private JSON API

Closes JSON Ledger API (open by default)

Default JVM Options

Default configuration options for the JVM running the validator

3.1 — Database Type

A PostgreSQL database will be created automatically.

  • Database User

  • Database Password

Connect to an external database of your choice.

  • Database User

  • Database Password

  • Host/IP address

  • Port number

4

Configure Resources

Configure the necessary resources:

  • Requested CPU

  • CPU limit

  • Requested memory

  • Memory limit

  • Replicas

More info about these fields
Field
Description

Requested CPU

Minimum amount of CPU resources requested for the validator node

CPU limit

Maximum amount of CPU resources the validator node is allowed to use

Requested memory

Minimum amount of memory requested for the validator node

Memory limit

Maximum amount of memory the validator node is allowed to use

Replicas

Number of instances of the validator node to run

The pre-filled figures for resource configuration are a standard recommendation. Please adapt to your unique scenario if needed.

5

Configure Environment Variables

Override the values of the environment variables for the following components:

  • Participant node

  • Validator backend

  • Canton Name Service UI

  • Wallet UI

More info about these components
Component
Description

Participant node

The node that interacts with the Canton ledger on behalf of participants

Validator backend

The backend service responsible for validating and processing transactions

Canton Name Service UI

The UI for managing and viewing Canton network names and identifiers

Wallet UI

User interface for interacting with the wallet associated with your validator

This is a very specific configuration. If you are not sure about this step, please contact IntellectEU.

6

Summary

Review your Validator configuration. Once you have confirmed the settings, click the Confirm button to finalize and proceed with the deployment.

7

Create a Permanent Password in Keycloak

To access the wallet UI, you must first define a new password in Keycloak.

  1. Save the credentials displayed in the pop-up window.

  2. Once your node is up and running, click on the last link containing the text wallet-web-ui, then click the link at the top left part of the screen.

  3. A pop-up will ask you to re-authenticate. Close your session by clicking the Log out button.

  4. Insert the temporary credentials saved in the previous step to authenticate yourself.

  5. Define a new password and click Submit. You will be forwarded to the wallet UI console of your new Validator.

Identity and Access Management

As part of the validator provisioning process, Keycloak is set as the identity provider for authentication and authorization across the validator infrastructure. Each validator is assigned a dedicated user ($VALIDATOR_NAME_walletuser) within a specific realm (validator) for secure access to services.

We strongly recommend updating the password for this user after the initial setup to maintain security and reduce risks associated with default credentials.

Resetting the Wallet User Password in Keycloak

1

Log in to the Keycloak admin console

  • URL: https://<your-keycloak-domain>/auth/admin/

  • Use an account with administrative access.

2

Navigate to the validator realm

From the top-left dropdown menu, select validator.

3

Locate the wallet user

In the left sidebar, click on Users and use the search field to find $VALIDATOR_NAME_walletuser.

4

Access the user's credentials

Click on the user to open their settings, then navigate to the Credentials tab.

5

Reset the password

  • Enter a new password and confirm it.

  • Toggle Temporary to OFF if you do not want the user to be forced to reset the password upon next login.

  • Click Reset Password.

6

Verify the changes

Test the new password by authenticating the service or using the Keycloak test login page (if enabled).

Make sure to store the new password securely and update any dependent services or configuration files if needed.

Additional Keycloak documentation resources
PreviousValidator Management
NextValidator Management with Custom Identity Provider

Last updated

Was this helpful?