Okta Setup Guide

Catalyst Blockchain Manager allows users to integrate with the OKTA platform for identity provision.

Along this guide, we show you how to set up you environment to enable the integration with OKTA.

1 - Catalyst Client Setup

To use Catalyst we need to configure two new clients.

  • Clients can be found in Applications→Application

1.1 - UI Client

The client the UI user will access, when creating choose the following options:

  • for Sign-in method choose: OIDC - OpenID Connect and for Application type choose: Single-Page Application

  • In Grant type select

    • Authorization code

    • Refresh Token

Once the client has been created:

  • In the client page go to LOGIN→Sign-in redirect URIs and add the following urls

    • <UI url>

    • <UI url>/domains

    • <UI url>/participants

    • <UI url>/domains

  • Add the same for Sign-in redirect URIs

1.2 - API Client

This client is used by the other components. When creating choose the following options:

  • For Sign-in method choose: OIDC - OpenID Connect and for Application type choose: Web Application

  • Go to the next form and on the Grant type select:

    • Client Credentials

    • Authorization Code

    • Refresh Token

The final result should look like it is displayed on the table bellow

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

2 - Catalyst user Access setup

The User has access to Catalyst Blockchain Manager console. You have to assign the users to the UI Client to access it. Additionally there are two roles that the user can to do operations in Catalyst canton_viewer and canton_writer these roles need to be added to the token. Bellow are instructions on how to add them.

2.1 - Set Role based access fields

To configure the roles field for role based access in the user profile

Profile Editor→User(default):

  • Select Add attribute choose string array

  • Set Display name as roles

  • Set Variable name as roles

Alternatively you can set the roles in Application User Profile, either way the field should look like this:
Application user profile roles
Figure 1. Application user profile roles

Next, go to Security→API→(The auth server you intend to use):

  • Go to Claims and select Add Claim

  • Name should be roles (must be this exact name as this will affect the token)

  • Include in token type: Access Token

  • Add the Value: user.roles if the field was added to the default user appuser.roles if it was added to the application user profile

  • Add Claim again with the same fields but change the “Include in token type” field to ID token

You can test the token in Security→API→Token preview, it should have a roles claim in the token with canton_viewer and canton_writer as shown bellow, for both id_token and token
Token preview
Figure 2. Token preview

3 - Add required fields to Helm charts

Fill in the following fields on the helm charts

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

  • auth.url : The issuer URI to obtain in the the Okta Admin interface:

    • Go to Security→API

    • Use the Issuer URI field shown in the default server

  • auth.client.idApiOperator : Select Applications→Applications and select API client we created and get the Client ID

  • auth.client.idUI : Select Applications→Applications and UI client we created and get the Client ID

  • auth.client.secret : Select Applications→Applications and API client we created and get the Client Secret

4 - Creating clients and users for the new validators

4.1 - CNS and Wallet clients

The clients for CNS and Wallet, when creating choose the following options, two separate clients can be created :

  • For Sign-in method choose: OIDC - OpenID Connect and for Application type choose: Single-Page Application

  • Go to the next form and in Grant type select:

    • Authorization Code

    • Refresh Token

After creating the validator go to the wallet page and obtain the wallet url this needs to be added to the redirect URI:

  • In the client page go to LOGIN→Sign-in redirect URIs and add that url

4.2 - Ledger Client

Client for the ledger, when creating:

  • for Sign-in method choose: API Services

The final result should look like it is displayed on the table bellow

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

4.3 - User

Assign any users needed to the Wallet and CNS, at least one user is needed as this will be the main wallet user and will be used when creating the validator

5 - Obtaining the fields to create the Validator in the UI

CNS Client Id, Wallet Client Id, Ledger API Client Id: On Aplications→Applications a list of clients with IDsis displayed

Ledger API Client Secret:

  • Can be found on the client page

Ledger API User:

  • Same as the Ledger API Client Id by default on okta

Wallet User:

  • The username for the main wallet user

Audience:

  • On Security→API check the Audience for the Auth server you are using