> 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-2.0/installation-instructions-canton/external-identity-provider-configuration-optional/okta-setup-guide.md).

# Okta Setup Guide

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

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

### Helm Chart Configuration

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

Fill in the following fields in your Helm chart values:

```yaml
auth:
  url: “”
  client:
    idApiOperator: “”
    idUI: “”
    secret: “”
```

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


---

# 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-2.0/installation-instructions-canton/external-identity-provider-configuration-optional/okta-setup-guide.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.