External Identity Provider Configuration (optional)

This section outlines the requirements for configuring an external Identity Provider (IdP) instead of the default integrated Keycloak.

When using an external IdP, CatalyX does not create users or OAuth clients for you; all required OIDC clients and users must be set up in your IdP before creating a validator, in accordance with the Canton Validator OIDC requirements.

This page covers the technical configuration requirements for external identity providers, including external IDP setup guides. For more details on the supported identity providers, see the Security & Privacy Implementation page.

Security & Privacy Implementation

The Identity Provider must be configured before launching a Canton Validator Node. This section provides a brief overview of configuring Clients and Users in your Identity Provider before setting up the Validator. For a full description of requirements, consult the Canton Validator OICD Requirements:

Kubernetes-Based Deployment of a Validator node — Splice documentationdocs.dev.sync.global

1. Identity Requirements

In this section, we describe the Identity requirements for the Catalyst platform and Canton Validator.

1.1. Catalyst Blockchain Manager

Catalyst integrates seamlessly with any OICD OAuth provider. The following information is expected from the Identity Provider:

• OICD Discovery

• Authorize Endpoint

• Token Endpoint

• Refresh Token endpoint

• JWKS endpoint

1.1.1. Clients

The clients required to set up a Canton validator with an IdP are explained below.

CNS Client ID (Public)

The requirements for the client are:

• Client ID.

• The client needs to support authorization code flow + token refresh.

• Configure redirect URIs based on the environment. Please request them from your Catalyst admin.

Client Catalyst API (Private)

This client is used by the Catalyst API. The main requirements are:

• Client ID.

• Client secret.

• The client needs to support authorization code flow + token refresh

• The requirement for an authorization code depends on the IdP and will be verified during the integration test.

• This client is used only for server-to-server interactions and does not require redirect URIs.

1.1.2. Users

To start using Catalyst, you must create a user for the administrator of the instance.

1.2. Canton Validator

The requirements for the OICD Provider are explained through the following docs:

Kubernetes-Based Deployment of a Validator node — Splice documentationdocs.dev.sync.global

1.2.1. Clients

Based on the documentation, the required clients for the Canton Validator are:

• CNS Client

  • Client ID

  • Redirect URI: Please request them from your Catalyst Admin.

• Wallet Client

  • Client ID

  • Redirect URI: Please request them from your Catalyst Admin.

• Ledger Client

  • Client ID

  • Ledger Client Secret

  • Ledger API User: The token needs a sub field. In most of the IdPs, the Client ID is the sub, but in others, it is required to create a service account logic to fill in this field correctly.

1.2.2. Users

The validator requires a wallet user account. This user is required to log in to the wallet application.

2. Canton JWT Requirements

From a security perspective, the components that comprise the Validator node must be able to authenticate with one another and with external UI and API users. Canton uses JTW access tokens for authentication and expects them to be issued by an external OpenID Connect (OIDC) provider.

Canton follows the OAuth 2.0 Authorization Framework, as defined in RFC 6749 and RFC 6750.

The Ledger API enforces some JWT dependencies that are described in the following documentation:

Configure API Authentication and Authorization with JWT — Digital Asset’s platform documentationdocs.digitalasset.com

Based on our experience, the changes should be the following:

• The configuration time-to-live for the client JWT tokens should be set to > 5 minutes.

• JWT Header Claim

• The typ claim should be “JWT”.

• JWT Payload Mandatory fields

• iss

• sub

• aud

• exp

• iat

• Scope: should be a list of strings separated by one space.

---