Authorization Setup

Configure JWT-based authentication for your Canton Network validator

Canton Network validators use JWT-based authentication through an OIDC (OpenID Connect) provider. This secures access to the Ledger API, Wallet UI, CNS UI, and the validator backend.

Production deployments must enable authentication. Running without authentication is acceptable only for local development and early DevNet testing.

How authentication works

The validator uses standard OIDC flows:

• Web UIs (Wallet, CNS) use Authorization Code flow with PKCE. Users authenticate through your OIDC provider’s login page, and the UI receives a short-lived access token.
• Backend services use Client Credentials flow. A service account authenticates directly with the OIDC provider to obtain a token for Ledger API access.
• The Ledger API validates JWT tokens using the JWKS (JSON Web Key Set) endpoint published by your OIDC provider.

Token requirements

Access tokens issued by your OIDC provider must include these claims:

• sub (subject) — Identifies the user or service account. For the validator admin, this must match the wallet admin user identity.
• aud (audience) — Must include https://canton.network.global for Ledger API access, and the validator API URL for UI access.
• scope — Must include daml_ledger_api for Ledger API operations.

Required OIDC clients

You need to register several clients (applications) with your OIDC provider:

• ledger-api — A resource server definition representing the Ledger API. Not a login client; used as an audience target.
• validator-app-backend — A confidential (service account) client using Client Credentials grant. The validator backend uses this to authenticate with the Ledger API.
• wallet-web-ui — A public client using Authorization Code + PKCE. Powers the Wallet UI login.
• cns-ui — A public client using Authorization Code + PKCE. Powers the CNS UI login.

OIDC provider options

Any OIDC-compliant provider works. The Splice documentation provides tested configurations for:

• Auth0 — Managed SaaS identity provider. Straightforward setup with tenant-level configuration.
• Keycloak — Open-source, self-hosted. Good for organizations that need full control over their identity infrastructure. Commonly used for LocalNet and DevNet.
• Okta — Enterprise identity provider with OIDC support.

Keycloak setup (LocalNet and DevNet)

Keycloak is a common choice for local development and DevNet because you can run it alongside your validator in Docker.

Realm configuration

Create a realm named canton with the following session settings:

• Offline session max lifespan: 5,184,000 seconds (60 days)
• Offline session idle timeout: 2,592,000 seconds (30 days)

Client scopes

Create a daml_ledger_api client scope with:

• A User Client Role mapper included in access tokens
• An Audience mapper set to https://canton.network.global

Create or modify the openid scope with:

• A Validator API Audience mapper set to https://validator-api.your-domain.example/api
• A Subject (sub) mapper included in access tokens

Client registration

Client ID	Type	Auth method	Purpose
ledger-api	Resource server	None	Audience target for Ledger API tokens
validator-app-backend	Confidential	Client credentials	Backend service authentication
wallet-web-ui	Public	Authorization Code + PKCE	Wallet UI login
cns-ui	Public	Authorization Code + PKCE	CNS UI login

User setup

Create a user whose username matches your validator’s party hint exactly. This user becomes the wallet admin operator.

The username must exactly match the party hint you used during onboarding. A mismatch prevents the wallet admin from functioning.

OIDC endpoints

Your validator needs three endpoints from your OIDC provider:

Token:     https://<oidc-host>/realms/canton/protocol/openid-connect/token
JWKS:      https://<oidc-host>/realms/canton/protocol/openid-connect/certs
Discovery: https://<oidc-host>/realms/canton/.well-known/openid-configuration

(Endpoint paths differ by provider. The above are Keycloak examples.)

Docker Compose configuration

Enable authentication by adding the -a flag to start.sh, then set these environment variables in your .env file:

AUTH_URL="https://<oidc-host>/realms/canton"
AUTH_JWKS_URL="https://<oidc-host>/realms/canton/protocol/openid-connect/certs"
AUTH_WELLKNOWN_URL="https://<oidc-host>/realms/canton/.well-known/openid-configuration"

VALIDATOR_AUTH_AUDIENCE="https://validator-api.your-domain.example/api"
VALIDATOR_AUTH_CLIENT_ID="validator-app-backend"
VALIDATOR_AUTH_CLIENT_SECRET="<client-secret>"

WALLET_ADMIN_USER="<keycloak-user-uuid>"
LEDGER_API_ADMIN_USER="<keycloak-user-uuid>"
LEDGER_API_AUTH_AUDIENCE="https://canton.network.global"

WALLET_UI_CLIENT_ID="wallet-web-ui"
ANS_UI_CLIENT_ID="cns-ui"

WALLET_ADMIN_USER and LEDGER_API_ADMIN_USER must be the Keycloak user UUID, not the username. Retrieve the UUID from the Keycloak admin console.

Kubernetes configuration

Set the equivalent values in your Helm values.yaml:

auth:
  jwksUrl: "https://<oidc-host>/realms/canton/protocol/openid-connect/certs"
  wellKnownUrl: "https://<oidc-host>/realms/canton/.well-known/openid-configuration"
validator:
  auth:
    audience: "https://validator-api.your-domain.example/api"
    clientId: "validator-app-backend"
    clientSecret:
      secretName: validator-auth-secret
      key: client-secret

Store client secrets in Kubernetes Secrets, not in Helm values files.

Running without authentication

For local development only, the validator can run without authentication. In Docker Compose, omit the -a flag. The validator issues self-signed tokens internally.

Running without authentication is insecure. Any client that can reach the Ledger API can act as any party. Never disable authentication on TestNet or MainNet.

Next steps

Configuration

Review other configuration options.

Upgrades

Plan for network upgrades.