Understanding Canton's Two Authentication Layers

Canton deployments expose two distinct authentication gates: one at the Validator App REST API, and one at the Participant Ledger API. You must configure both correctly—a working wallet can still fail when the validator talks to the participant.

The Mental Model

External clients (browsers, mobile apps) hit the Validator App REST endpoints through the wallet UI. The Validator App then calls the Participant's gRPC Ledger API using machine-to-machine authentication. This split is why you see two disableAuth toggles in two different Helm values files.

Layer 1: Validator App REST Auth

This layer governs calls to the Validator App REST API (commonly on ports 5003/5103) and directly impacts wallet UI flows and /api/validator/* endpoints.

• When disableAuth: false — The Validator App validates JWTs using the configured JWKS URL and audience.
• When disableAuth: true — The Validator App switches to an "unsafe" HMAC-style mechanism intended for non-production usage.

disableAuth: false

auth:
  audience: "https://canton.network.global"
  jwksUrl: "https://your-keycloak/realms/canton/protocol/openid-connect/certs"

Layer 2: Participant Ledger API Auth

This layer governs every gRPC call to the Participant Ledger API (commonly on port 5001), including calls made by the Validator App itself and by any custom applications you build.

• When disableAuth: false — The participant validates JWTs for all Ledger API calls using the configured JWKS.
• When disableAuth: true — The participant accepts unauthenticated calls. Only appropriate for local development.

disableAuth: false

auth:
  targetAudience: "https://canton.network.global"
  jwksUrl: "https://your-keycloak/realms/canton/protocol/openid-connect/certs"

Configuration Matrix

Different combinations of these settings are appropriate for different environments:

Common Gotchas

"Wallet login works, but transactions fail"

This often means Layer 1 is correct but Layer 2 is rejecting the validator's Ledger API calls. Check that your validator-to-participant M2M client credentials are properly configured and that the participant's JWKS URL is reachable.

"Everything worked in dev, fails in prod"

This typically happens because both layers were set to true in development, and only one layer was properly configured with JWKS/audience when moving to production.

"M2M works for validator, but my custom app fails"

When participant auth is enabled, all clients need valid JWTs—not just the validator. Your custom application must also obtain and present valid tokens for every Ledger API call.

Debug Checklist

1. Confirm both configs — Check validator-values.yaml andparticipant-values.yaml. Don't troubleshoot only one layer.
2. Verify JWKS URL is reachable — From inside the cluster, not just your local machine.
3. Decode the JWT — Check that aud andsub claims match what Canton expects.
4. Check logs on BOTH components — Either layer can reject the request flow.

# Validator App logs
kubectl logs -l app=validator-app -n validator

# Participant logs  
kubectl logs -l app=participant -n validator

Connection to Canton Identity

Canton's synchronization layer relies on shared, verifiable identity and topology information so nodes can make consistent decisions. The "shared understanding of identities" is managed by the Identity Providing Service (IPS), which maps parties to participants and manages associated cryptographic keys.

The two authentication layers we've discussed here are the access control mechanism that sits in front of this identity infrastructure, determining who can make requests in the first place.