> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-1.10/validator-management/create-validator-with-custom-identity-provider.md).

# Create Validator with Custom Identity Provider

{% hint style="info" %}
The alternative to this approach is using Integrated Keycloak, which automates the process as detailed in [Create Validator with Integrated Keycloak](broken://pages/f103cefdb6247b38919caf1c1aae134da2406c0c).
{% endhint %}

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](https://network.canton.global/validator_operator/validator_helm.html#oidc-provider-requirements).

{% hint style="info" %}
The sections on secrets and other Kubernetes configuration can be ignored — Catalyst creates them. Clients and users need to be set up beforehand.
{% endhint %}

## 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:

{% hint style="warning" %}
It is recommended to allow all audiences for the clients when creating the validator. These can be restricted later once Catalyst generates the URLs.
{% endhint %}

| Validator Component | OpenID Flow              | Fields required by Catalyst |
| ------------------- | ------------------------ | --------------------------- |
| 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.

{% hint style="info" %}
This user will be mapped to the main Validator party and will receive rewards, which can be viewed from the Wallet.
{% endhint %}

***

## Set Up a Validator

{% stepper %}
{% step %}

#### 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

<details>

<summary>More info about these fields</summary>

| Field                 | Description                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| **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                                               |

</details>

{% hint style="info" %}
An onboarding secret should be requested from your sponsoring SV in order to join the network.
{% endhint %}

{% hint style="danger" %}
Make sure to set the **Custom Authentication** flag **ON**.
{% endhint %}

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

<details>

<summary>More info about custom authentication fields</summary>

| Field                        | Description                                                               |
| ---------------------------- | ------------------------------------------------------------------------- |
| **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                                    |

</details>

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}

{% step %}

#### 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

<details>

<summary>More info about these fields</summary>

| Field                            | Description                                                      |
| -------------------------------- | ---------------------------------------------------------------- |
| **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    |

</details>
{% endstep %}

{% step %}

#### Cluster Participant Configuration

* Insert your default JVM configurations
* Enable or disable: **Enable health probes**
* Insert your **Node Identifier**
  {% endstep %}

{% step %}

#### Configure Resources

* Requested CPU, CPU limit, Requested memory, Memory limit, Replicas
  {% endstep %}

{% step %}

#### Configure Environment Variables

Override environment variables for: Participant node, Validator backend, Canton Name Service UI, Wallet UI.

{% hint style="danger" %}
This is a very specific configuration. If you are not sure about this step, please contact IntellectEU.
{% endhint %}
{% endstep %}

{% step %}

#### Summary

Review your Validator configuration. Click **Confirm** to finalize and proceed with the deployment.
{% endstep %}
{% endstepper %}

***

## Identity and Access Management

In deployments where an external Identity Provider is used, your organization is responsible for managing user credentials and access controls.

{% hint style="danger" %}
We strongly recommend updating the password for the wallet user after the initial setup.
{% endhint %}

### Resetting the Wallet User Password

Refer to the official documentation for your IdP. Typical steps:

1. Log into your Identity Provider's admin portal.
2. Locate the user account associated with the validator (e.g., `$VALIDATOR_NAME_walletuser`).
3. Initiate a password reset or manual update from the user management section.
4. Disable any temporary password flags if you want to use the new password directly.
5. Update any validator configuration files or services that use this credential.

{% hint style="warning" %}
If your IdP integrates with federation or SSO, ensure policies and password propagation are correctly applied.
{% endhint %}

<details>

<summary>Common IdP documentation resources</summary>

* [Azure AD User Management](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/)
* [Okta Admin Guide](https://help.okta.com/)
* [Auth0 Password Reset](https://auth0.com/docs/authenticate/login/password-reset)

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-1.10/validator-management/create-validator-with-custom-identity-provider.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.