External Identity Provider

Configure a validator against OIDC clients you create yourself, in any OIDC-compliant identity provider.

With spec.auth.managedKeycloak: false — the default — you create the OIDC objects yourself and reference them from the Validator resource. This works with any OIDC-compliant identity provider, including Okta, Microsoft Entra ID, Auth0, and Ping Identity.

What to create in your identity provider

Object	Type	Used by
Wallet UI client	Public	The Canton Wallet web UI. Needs a redirect URI of https://wallet-<validator-name>.<baseHostname>/* and the matching web origin.
CNS UI client	Public	The Canton Name Service web UI. Redirect URI https://cns-<validator-name>.<baseHostname>/*.
Backend client	Confidential	The validator app, PQS, and the Wallet Gateway, for machine-to-machine access to the Ledger API. Needs the client credentials grant enabled.
Wallet Gateway client	Public	Only when the Wallet Gateway is enabled. Redirect URI https://wallet-gateway-<validator-name>.<baseHostname>/*.
Participant admin user	User	The Canton participant's admin user identity.
Wallet user	User	The user the validator app treats as the wallet owner.

Every token issued to these clients must carry the audience you configure as spec.auth.targetAudience. Add an audience mapper or equivalent to each client.

Store the backend client secret

kubectl create secret generic my-validator-ledger-api-auth \
  --from-literal=client-secret=<backend-client-secret> \
  -n <namespace>

---

Configuration

spec:
  auth:
    enabled: true
    managedKeycloak: false

    authUrl: https://idp.example.com/realms/canton
    jwksUrl: https://idp.example.com/realms/canton/protocol/openid-connect/certs
    targetAudience: https://canton.network.global
    ledgerApiUserManagementScope: daml_ledger_api

    ledgerApiUser: participant-admin
    walletUserName: wallet-user

    ledgerApiClientId: my-validator-backend
    walletUiClientId: my-validator-wallet-ui
    cnsUiClientId: my-validator-cns-ui
    ledgerApiClientSecretRef:
      name: my-validator-ledger-api-auth
      key: client-secret

Field reference

Field	Purpose
authUrl	OIDC issuer URL. Used by the UIs, and by the validator app, PQS, and Wallet Gateway to obtain tokens. Either an issuer URL or a token endpoint is accepted — an issuer URL is discovered via .well-known/openid-configuration.
jwksUrl	JWKS endpoint the participant and validator app verify tokens against.
targetAudience	The audience every token must carry.
ledgerApiUserManagementScope	The OAuth scope that grants Ledger API user-management rights.
ledgerApiUser	The participant's admin user name.
walletUserName	The wallet owner's user name.
ledgerApiClientId	The confidential backend client ID.
walletUiClientId / cnsUiClientId	The public client IDs for the two web UIs.
walletGatewayClientId	The public client ID for the Wallet Gateway. Required only when the Wallet Gateway is enabled.
ledgerApiClientSecretRef	Secret holding the backend client secret. key defaults to client-secret.

None of these fields is marked required in the CRD schema, so a Validator missing them will be accepted by the API server and then fail during reconciliation. The Ready condition will report InvalidSpec with the name of the missing field. Check the condition after applying.

The walletGatewayClientId field cannot currently be set through the catalyx-canton-validator Helm chart. If you use that chart and need the Wallet Gateway with an external identity provider, apply the Validator resource directly instead.

---

Verifying

Open the validator's Identity tab in the UI. It shows Managed Keycloak: External, the resolved auth URL, the target audience, and each client ID — a quick way to confirm the values reached the components.

If tokens are being rejected, the usual causes are:

• the audience mapper is missing on one of the clients, so targetAudience does not match;

• the redirect URI registered on a public client does not match the hostname the operator generated from operatorRuntime.baseHostname;

• the client credentials grant is not enabled on the backend client.

---

Disabling authentication

spec.auth.enabled: false disables authentication on the participant entirely.

Never do this outside a local development cluster. It leaves the Ledger API open to anyone who can reach it.