> 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/operations-guide/okta-setup-guide.md).

# Okta Setup Guide

Catalyst Blockchain Manager allows users to integrate with the Okta platform for identity provision. This guide shows you how to set up your environment to enable the integration.

{% stepper %}
{% step %}

#### Catalyst Client Setup

Two new clients need to be configured in Okta. Go to **Applications → Applications** to manage clients.

**UI Client**

For the client that UI users will access, select:

* **Sign-in method:** OIDC - OpenID Connect
* **Application type:** Single-Page Application
* **Grant type:** Authorization Code + Refresh Token

Once the client has been created, go to **LOGIN → Sign-in redirect URIs** and add:

* `<UI url>`
* `<UI url>/domains`
* `<UI url>/participants`

Add the same for **Sign-out redirect URIs**.

**API Client**

This client is used by the other components. Select:

* **Sign-in method:** OIDC - OpenID Connect
* **Application type:** Web Application
* **Grant type:** Client Credentials + Authorization Code + Refresh Token

**Summary of both clients:**

| 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               |
| {% endstep %} |                       |                         |                                                       |                   |

{% step %}

#### Catalyst User Access Setup

Users must be assigned to the UI Client. Two roles control access: `canton_viewer` and `canton_writer`. These must be added to the token.

**Set Role-Based Access Fields**

**In Profile Editor → User (default):**

* Select **Add attribute** → choose **string array**
* Set **Display name** as `roles`
* Set **Variable name** as `roles`

{% hint style="info" %}
Alternatively, you can set the roles in Application User Profile. Either way the field should have the same structure.
{% endhint %}

**In Security → API → (your auth server):**

1. Go to **Claims** and select **Add Claim**
2. **Name:** `roles` (must be this exact name — it affects the token)
3. **Include in token type:** Access Token
4. **Value:** `user.roles` (default user) or `appuser.roles` (application user profile)
5. Add the claim again with **Include in token type:** ID Token

{% hint style="info" %}
Test the token in **Security → API → Token preview**. It should have a `roles` claim with `canton_viewer` and `canton_writer` for both `id_token` and `token`.
{% endhint %}
{% endstep %}

{% step %}

#### Add Required Fields to Helm Charts

```yaml
auth:
  url: ""
  client:
    idApiOperator: ""
    idUI: ""
    secret: ""
```

| Field                       | Where to find it                                             |
| --------------------------- | ------------------------------------------------------------ |
| `auth.url`                  | **Security → API** → Issuer URI of the default server        |
| `auth.client.idApiOperator` | **Applications → Applications** → API client → Client ID     |
| `auth.client.idUI`          | **Applications → Applications** → UI client → Client ID      |
| `auth.client.secret`        | **Applications → Applications** → API client → Client Secret |
| {% endstep %}               |                                                              |

{% step %}

#### Creating Clients and Users for New Validators

**CNS and Wallet Clients**

Create two separate clients with:

* **Sign-in method:** OIDC - OpenID Connect
* **Application type:** Single-Page Application
* **Grant type:** Authorization Code + Refresh Token

After creating the validator, add the wallet URL to the **Sign-in redirect URIs** of the Wallet client.

**Ledger Client**

For the Ledger client, select **API Services** as the Sign-in method.

**Summary of validator clients:**

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

**User**

Assign at least one user to the Wallet and CNS clients. This user will be the main wallet user when creating the validator.
{% endstep %}

{% step %}

#### Obtaining Fields to Create the Validator in the UI

| Field                        | Where to find it                                                |
| ---------------------------- | --------------------------------------------------------------- |
| **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** | Ledger client page → Client Secret                              |
| **Ledger API User**          | Same as the Ledger API Client Id by default on Okta             |
| **Wallet User**              | Username of the main wallet user                                |
| **Audience**                 | **Security → API** → Audience for the auth server you are using |
| {% endstep %}                |                                                                 |
| {% endstepper %}             |                                                                 |


---

# 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/operations-guide/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.