Create Validator with Custom Identity Provider
The alternative to this approach is using Integrated Keycloak, which automates the process as detailed in Create Validator with Integrated Keycloak.
When installing Catalyst, it is configured with an Identity Provider used to authenticate Catalyst and the validators deployed through it.
This is a brief overview of how to set up Clients and Users in your Identity Provider before setting up the Validator. For a full description of requirements, consult the Canton Validator OIDC requirements.
The sections on secrets and other Kubernetes configuration can be ignored — Catalyst creates them. Clients and users need to be set up beforehand.
Prerequisites: Configure Your Identity Provider
Clients
The following clients are used by a Validator node and must be configured with the proper flows in your Identity Provider:
It is recommended to allow all audiences for the clients when creating the validator. These can be restricted later once Catalyst generates the URLs.
Validator
Client Credentials Grant
Client Id, Client secret
Canton Name Service
Authorization Code
Client Id
Wallet
Authorization Code
Client Id
Users
A single user needs to be created beforehand with access to the clients created.
This user will be mapped to the main Validator party and will receive rewards, which can be viewed from the Wallet.
Set Up a Validator
Main Settings Configuration
Provide the following information:
Name, Onboard secret, Image tag, Image repo, Image pull secret
Postgres user, Postgres password
Requested CPU, CPU limit, Requested memory, Memory limit, Replicas
More info about these fields
Name
The identifier or label for the validator node
Onboard secret
Passphrase obtained from the super validator
Image tag
The specific version or tag of the container image
Image repo
The repository where the container image is stored
Image pull secret
Credentials required to pull the container image from a private registry
Postgres user
Username for the Postgres database
Postgres password
Password for the Postgres database user
Requested CPU
Minimum CPU resources requested
CPU limit
Maximum CPU resources allowed
Requested memory
Minimum memory requested
Memory limit
Maximum memory allowed
Replicas
Number of instances to run
An onboarding secret should be requested from your sponsoring SV in order to join the network.
Make sure to set the Custom Authentication flag ON.
Now set the custom authentication fields:
CNS Client Id
Wallet Client Id
Ledger API Client Id
Ledger API Client Secret
Ledger API User
Wallet User
Audience
More info about custom authentication fields
CNS Client Id
Client for the Canton Name Service
Wallet Client Id
Client for the Wallet application
Ledger API Client Id
Client for the Validator
Ledger API Client Secret
Secret part of the Client Credentials Grant Flow for the Validator client
Ledger API User
User of the components described above
Wallet User
User that will access the wallet application and receive rewards
Audience
Audience claim expected by the clients
The value for Ledger API User and Wallet User depends on the Identity Provider — use what the IdP puts as the subject field in the JWT token.
Cluster Configuration
2.1 — Enable or disable:
Enable wallet
Fail on app version mismatch
Use sequencer connections from scan
2.2 — Fill in the remaining fields:
Cluster URL, Disable wallet, Scan address, SV Sponsor Address, Party hint, Default JVM Options
Migration: Id, Migrating
Top up: Enable, Top up min interval, Target throughput
2.3 — Enable or disable:
Participant identities dump import
Participant identities dump periodic backup
More info about these fields
Cluster URL
URL of the Kubernetes cluster where the validator is deployed
Disable wallet
Turn on to not deploy a wallet UI with your validator
Fail on app version mismatch
Deployment fails on version mismatch if enabled
Scan address
Address used for scanning and retrieving validator-related data
SV Sponsor Address
URL of the SV app sponsoring you (starts with https://sv.sv-N)
Party hint
Prefix for the Party ID. Format: <org>-<function>-<enumerator>
Default JVM Options
Default JVM configuration options
Migrating
Set to true when upgrading to trigger the migration process
Identity and Access Management
In deployments where an external Identity Provider is used, your organization is responsible for managing user credentials and access controls.
We strongly recommend updating the password for the wallet user after the initial setup.
Resetting the Wallet User Password
Refer to the official documentation for your IdP. Typical steps:
Log into your Identity Provider's admin portal.
Locate the user account associated with the validator (e.g.,
$VALIDATOR_NAME_walletuser).Initiate a password reset or manual update from the user management section.
Disable any temporary password flags if you want to use the new password directly.
Update any validator configuration files or services that use this credential.
If your IdP integrates with federation or SSO, ensure policies and password propagation are correctly applied.
Last updated
Was this helpful?