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

Okta Setup Guide

CatalyX Blockchain Manager supports Okta as an external Identity Provider. This section walks through the steps required to configure Okta before creating a validator in CAT-BM.

Catalyst Client Setup

Two clients must be created in Okta under Applications → Applications.

UI Client

The UI client is used by the CAT-BM console. When creating it, select the following options:

  • Sign-in method: OIDC - OpenID Connect

  • Application type: Single-Page Application

  • Grant type: Authorization Code and Refresh Token

Once created, navigate to LOGIN → Sign-in redirect URIs and add the following URLs:

  • <UI url>

  • <UI url>/domains

  • <UI url>/participants

Add the same URLs to the Sign-out redirect URIs.

API Client

This client is used by the CAT-BM API and other backend components. When creating it, select:

  • Sign-in method: OIDC - OpenID Connect

  • Application type: Web Application

  • Grant type: Client Credentials, Authorization Code, and Refresh Token

Client
Sign-in Method
Application Type
Grant Types
Has Client Secret

UI

OIDC - OpenID Connect

Single-Page Application

Authorization Code; Refresh Token

No

API

OIDC - OpenID Connect

Web Application

Client Credentials; Authorization Code; Refresh Token

Yes

User Access Setup

CAT-BM enforces role-based access using two roles: canton_viewer (read-only) and canton_writer (full operational access). These roles must be added to the Okta token.

Step 1 — Add the roles attribute to the user profile:

Go to Profile Editor → User (default):

  • Select Add Attribute and choose String Array

  • Set Display name to roles

  • Set Variable name to roles

Step 2 — Add the roles claim to the token:

Go to Security → API → [your auth server] → Claims and select Add Claim:

  • Name: roles (must be this exact name)

  • Include in token type: Access Token

  • Value: user.roles (or appuser.roles if added to the application user profile)

Repeat with Include in token type set to ID Token.

You can verify the token in Security → API → Token Preview. The token should contain a roles claim with canton_viewer and canton_writer values in both the id_token and token.

Helm Chart Configuration

GitOps transition note: CatalyX Blockchain Manager is moving toward a GitOps-driven deployment model using Helm charts managed via ArgoCD. The Helm chart field references below reflect the current configuration approach. These may change as the GitOps model matures — confirm with the engineering team for the latest guidance on your deployment.

Fill in the following fields in your Helm chart values:

  • auth.url — The Issuer URI from Security → API → [your auth server] (the Issuer URI field on the default server)

  • auth.client.idApiOperator — Client ID of the API client, found under Applications → Applications

  • auth.client.idUI — Client ID of the UI client, found under Applications → Applications

  • auth.client.secret — Client Secret of the API client, found on the client's page

Validator Client Setup

Before creating a validator in CAT-BM, three additional clients must be created in Okta.

CNS and Wallet Clients

Create two separate clients with the following options:

  • Sign-in method: OIDC - OpenID Connect

  • Application type: Single-Page Application

  • Grant type: Authorization Code and Refresh Token

After creating the validator, retrieve the Wallet URL from the Wallet page and add it to LOGIN → Sign-in redirect URIs on the Wallet client.

Ledger Client

  • Sign-in method: API Services

Client
Sign-in Method
Application Type
Grant Types
Has Client Secret

Wallet

OIDC - OpenID Connect

Single-Page Application

Authorization Code; Refresh Token

No

CNS

OIDC - OpenID Connect

Single-Page Application

Authorization Code; Refresh Token

No

Ledger

API Services

—

—

Yes

Assign at least one user to both the Wallet and CNS clients — this will be the main wallet user when creating the validator.

Obtaining Fields for Validator Creation

When creating a validator in CAT-BM with Okta as the IdP, the following fields are required:

Field
Where to find it in Okta

CNS Client ID

Applications → Applications → CNS client → Client ID

Wallet Client ID

Applications → Applications → Wallet client → Client ID

Ledger API Client ID

Applications → Applications → Ledger client → Client ID

Ledger API Client Secret

Applications → Applications → Ledger client → Client Secrets tab

Ledger API User

Same as the Ledger API Client ID by default in Okta

Wallet User

Username of the main wallet user account

Audience

Security → API → [your auth server] → Audience field

Last updated

Was this helpful?