Security & Privacy Implementation
This section covers the security & privacy design for CatalyX Blockchain Manager, including authentication, infrastructure hardening, key management, external wallet integration & compliance controls.
The CAT-BM solution has been designed with a strong emphasis on enterprise-grade security and data privacy, leveraging modern cloud-native capabilities and best practices in identity management, access control, and cryptographic key protection.
Overview
Authentication and Authorization (IDPs)
Infrastructure Security
Key Management (KMS) and External Wallets
Privacy Controls
1. Authentication and Authorization
1.1 OIDC-based Identity Management
All users and system components in CatalyX Blockchain Manager authenticate via OpenID Connect (OIDC) — an identity layer built on top of OAuth 2.0. OIDC allows CAT-BM and Canton validator nodes to verify the identity of users and services by validating signed JWT access tokens issued by a trusted Identity Provider (IdP).
CAT-BM supports two identity management paths:
Integrated Keycloak (default) — CAT-BM ships with a built-in Keycloak instance that is automatically configured during deployment. This is the recommended path for most deployments and requires no external IdP setup.
External Identity Provider — Organizations that already operate their own IdP (such as Microsoft Entra ID, Auth0, Okta, or another OIDC-compliant provider) can connect it instead of using the integrated Keycloak. In this mode, the customer is responsible for pre-configuring the required OIDC clients and users in their IdP before creating a validator.
Regardless of which IdP path is chosen, Canton validator nodes authenticate all API calls using JWT tokens and follow the OAuth 2.0 Authorization Framework (RFC 6749 / RFC 6750). The IdP must satisfy Canton's OIDC provider requirements, documented by Digital Asset here.
Roadmap: CatalyX Blockchain Manager is moving toward a fully provider-agnostic OIDC model. In this future state, CAT-BM will act as a pure OIDC consumer — accepting any compliant provider by configuration, without provider-specific integration code. Customers will manage their own IdP resources (clients, users, scopes) externally, and CAT-BM will discover endpoints automatically via the standard OIDC discovery mechanism (/.well-known/openid-configuration).
For the technical configuration steps required before creating a validator with an external IdP — including client setup, JWT requirements, and redirect URI configuration — see the Installation Instructions page:
External Identity Provider Configuration (optional)1.1.1 Integrated Keycloak (Default)
Keycloak is an open-source Identity and Access Management solution maintained by Red Hat. It provides SSO (Single Sign-On), OAuth 2.0 / OIDC token issuance, user federation, and fine-grained access control out of the box.
Architectural role
In the CBM component architecture, the Identity Provider is a dedicated system component responsible for user management and access-token issuance. The authentication flow works as follows:
The Canton Operator (human user) opens the CAT-BM UI.
Both the UI and the operator request access tokens from Keycloak.
The UI calls the CAT-BM API over REST, passing the access token for every request.
The API validates the token against Keycloak's JWKS endpoint (
{keycloak-url}/auth/realms/{realm}/protocol/openid-connect/certs) and extracts the user's roles from the JWTrolesclaim.Two roles are enforced:
canton_viewer(read-only access) andcanton_writer(full operational access).
In the default CAT-BM deployment, Keycloak is deployed as a managed service within the same Kubernetes cluster as the validator. CatalyX automatically provisions the required realm, OIDC clients, and service users as part of the validator setup — operators do not need to configure Keycloak manually.
What Keycloak manages in a default CAT-BM deployment:
A dedicated realm scoped to the CAT-BM environment
Three OIDC clients: the Validator (client credentials), the Canton Name Service UI (authorization code), and the Wallet UI (authorization code)
A wallet user account for accessing the Wallet UI
JWT token issuance with the correct claims (
iss,sub,aud,exp,iat,scope) expected by the Canton Ledger APIAudience scopes mapped to each client for Canton token validation
Credential types used by CAT-BM:
Client ID + Client Secret
Validator backend (server-to-server)
Client Credentials Grant
Client ID
CNS UI, Wallet UI
Authorization Code + PKCE
Wallet user account
End users accessing the Wallet
Authorization Code
How to check and use credentials
Credentials for all Keycloak clients are accessible via the Keycloak Admin Console:
Navigate to your Keycloak admin URL (
{keycloak-url}/auth/admin/)Select the
validatorrealm from the top-left dropdownGo to Clients in the left sidebar to view all configured OIDC clients
Select a client to view its Client ID; for confidential clients, navigate to the Credentials tab to retrieve or regenerate the Client Secret
To inspect a user's roles and token configuration, go to Users → select the user → Role Mappings tab
Keycloak database: Each environment runs a dedicated PostgreSQL instance for Keycloak, isolated from the Canton ledger database (see section 2.3).
Wallet user account: During validator creation, CatalyX automatically creates a wallet user in Keycloak named <validator-name>_walletuser, scoped to the validator realm.
It is strongly recommended to reset the wallet user password immediately after initial setup via the Keycloak Admin Console. Navigate to your Keycloak admin URL → select the validator realm → Users → search for <validator-name>_walletuser → Credentials tab → Reset Password (set Temporary to OFF).
Disaster recovery
Keycloak's configuration and user data are stored in its dedicated PostgreSQL database. Recovery is handled as part of the broader CAT-BM DR strategy:
Database backup restoration — Keycloak state is recovered from regular PostgreSQL backups. RTO target: 1 hour. RPO target: 4 hours under a database backup/restore scenario; near 0 for multi-region active/standby deployments.
Regional failover — in a multi-region setup, the Keycloak database can be failed over to a secondary region operating in passive or warm standby mode.
The DR plan is reviewed and tested at least annually.
Detailed Keycloak-specific DR procedures (e.g. realm export/import, step-by-step restore runbook) are to be confirmed with the engineering team.
For full Keycloak documentation, see the official docs:
For step-by-step setup guidance, see:
Setup1.1.2 Microsoft Entra ID
Microsoft Entra ID (formerly Azure Active Directory) is Microsoft's cloud-based identity platform. It is the natural choice for organisations already running on Microsoft 365 or Azure, as it enables validators to authenticate using the same enterprise identity infrastructure without running a separate Keycloak instance.
How Entra ID differs from other OIDC providers
Entra ID is fully OIDC-compliant but has one important behavioural difference in its OAuth 2.0 client credentials flow: it does not accept an audience parameter on the token endpoint. Instead, it requires a scope value using the .default suffix format:
For Ledger API calls (parties, users, DAR files):
<ledger_client_id>/.defaultFor Validator API calls (identity dump):
api://<ledger_client_id>/.default
Without this scope format, Entra ID rejects token requests with an AADSTS error. CatalyX Blockchain Manager automatically handles this scope logic when a validator is configured with Entra ID as the IdP — no manual workaround is required from version 1.11.10 onwards.
For step-by-step setup guidance, see the dedicated EntraID setup guide:
Microsoft EntraID Setup GuideFor further reference on Entra ID OIDC configuration, see the Microsoft identity platform documentation:
1.1.3 Auth0
Auth0 is a cloud-based identity platform by Okta that provides authentication and authorisation as a service. It is well suited for organisations that want a fully managed, developer-friendly IdP without operating their own identity infrastructure.
How Auth0 works with CAT-BM
Auth0 is a natively supported provider in CAT-BM. When configured, CAT-BM uses Auth0's standard OIDC discovery endpoint and validates JWT tokens against Auth0's JWKS endpoint at {baseUri}/.well-known/jwks.json.
Auth0 support in CAT-BM covers:
SPA application client creation for the CNS and Wallet UIs
Ledger API resource server configuration
Token acquisition via client credentials flow for server-to-server authentication
Token refresh handling via the Auth0 Management API
Auth0 is disabled by default and must be explicitly enabled via configuration. The same three OIDC clients (Validator, CNS, Wallet) and wallet user account are required as with any external IdP.
For step-by-step setup guidance, see the dedicated Auth0 setup guide:
Auth0 Setup GuideFor Auth0's official documentation:
1.1.4 Okta
Okta is an enterprise identity platform widely used for workforce and customer identity management. It is a natural fit for organisations already using Okta for SSO across their application landscape.
How Okta works with CAT-BM
Okta is a supported OIDC provider for CatalyX Blockchain Manager validators. It uses the standard OAuth 2.0 / OIDC flows and exposes a standard discovery endpoint, making it compatible with CAT-BM's generic OIDC configuration. The authorize endpoint follows the pattern https://{your-domain}.okta.com/oauth2/default/v1/authorize.
The same three OIDC clients (Validator, CNS, Wallet) and wallet user account are required as with any external IdP.
For step-by-step setup guidance, see the dedicated Okta setup guide:
Okta Setup Guide1.1.5 Other External Identity Providers
CatalyX Blockchain Manager supports any OIDC-compliant Identity Provider. If your organisation uses a provider not listed above (such as PingIdentity, Google, or a custom OIDC server), the general configuration requirements are the same: you must pre-configure the three required OIDC clients (Validator, CNS, Wallet) and a wallet user account in your IdP before creating a validator in CAT-BM.
For the full set of OIDC and JWT requirements that any external provider must satisfy, refer to:
External Identity Provider Configuration (optional)1.2 Role-Based Access Control (RBAC)
CAT-BM enforces fine-grained access controls based on user roles defined in the user access token. This includes permission boundaries for deployment operations, audit views, and runtime configurations. Each user role (e.g., Admin, Operator, Auditor) is mapped to a specific set of capabilities within the system.
2. Infrastructure Security
2.1 Cloud Environment
The CAT-BM platform is hosted on Azure AKS, which provides managed Kubernetes with integrated Azure security features, including IAM roles for service accounts (IRSA), VNet isolation, and encrypted storage.
2.2 Network Security
Ingress is controlled using Kubernetes ingress controllers, secured with HTTPS and mutual TLS where applicable.
Internal communication between services within the AKS cluster is protected using Kubernetes Network Policies, ensuring fine-grained, pod-level traffic controls. For workloads requiring stronger guarantees, a service mesh such as Istio or Linkerd can provide mutual TLS, automatic certificate rotation, and traffic encryption between microservices.
All Kubernetes control plane communications are secured by AKS, with encryption in transit between worker nodes and the managed control plane. Private AKS endpoints can be enabled to ensure that Kubernetes API access is limited to internal networks via VNet endpoints or VPN/Direct Connect, preventing exposure to the public internet.
DNS traffic inside the cluster is secured through CoreDNS and VNet DNS resolution, while external service access can be restricted with egress controls, including Kubernetes egress policies, NAT gateways, or Azure Network Firewall.
2.3 Database Security
Each environment (DevNet, TestNet, MainNet) uses two Azure Database for PostgreSQL Flexible Server (managed database service) instances: one hosting the Keycloak database and one hosting the validator and participant databases.
Databases are protected through Azure-managed encryption at rest, TLS encryption in transit, role-based access control with least-privilege service accounts, and network access restrictions. High availability is configured with multi-zone synchronous replication and automatic failover (see HA & DR sections). Azure-managed backups with point-in-time recovery protect against data loss. Database activity is logged through PostgreSQL server logs and Azure platform monitoring, providing audit visibility into database access and infrastructure changes.
Each environment contains two database servers:
Azure PostgreSQL Server for Keycloak
Keycloak database
Identity and access management data
Azure PostgreSQL Server for Validator
Participant database, validator database
Canton validator and participant ledger data
Separating these workloads across two PostgreSQL servers provides logical isolation of identity infrastructure from ledger infrastructure.
The following accounts are used for database level access:
Azure PostgreSQL Server for Keycloak
keycloak
keycloakadmin - administrator user
Keycloak service
Read / Write, schema management (non-superuser)
Azure PostgreSQL Server for Validator
participant
cnadmin - administrator user
Canton participant service
Read / Write, schema management (non-superuser)
Azure PostgreSQL Server for Validator
validator
cnadmin - administrator user
Canton validator service
Read / Write, schema management (non-superuser)
2.4 Environment Guardrails
Objective: Prevent misconfigurations and enforce data residency using Policy as Code.
Policy Enforcement Engine: Deployed Azure Policy Initiatives to act as automated platform guardrails.
Security Baselines: The Microsoft Cloud Security Benchmark has been applied to the environment.
Devnet: Configured in Audit Mode for visibility.
Mainnet: Configured in Deny Mode to actively block insecure deployments (e.g., blocking Public IPs on Canton nodes, mandating disk encryption).
Data Residency Restrictions: Implemented strict Allowed Locations policies at the Resource Group level. This acts as a geofence, ensuring Canton nodes and data can only be deployed in approved Azure regions (e.g., eastus2).
2.5 Compliance & Vulnerability Monitoring
Continuous Threat Detection: Activated Microsoft Defender for Cloud across all workload types:
Defender for Servers (AKS Nodes)
Defender for Containers (AKS Orchestration/Pods)
Defender for Open-Source Relational Databases (PostgreSQL)
Defender for Key Vaults & Storage
Agentless Vulnerability Scanning: Enabled Agentless Scanning and MDE (Microsoft Defender for Endpoint) integration. This provides daily CVE discovery on OS and software packages with zero performance impact on the Canton nodes.
Regulatory Dashboard: Mapped the environment to the SOC 2 Type II regulatory standard. Real-time compliance scores and exportable auditor reports (PDFs) are now generated automatically.
2.6 Open Source Libraries
Software/components/libraries and their licenses used on CatalyX Blockchain Manager can be found in the Open Source Licenses documentation.
Open Source Licenses3. Key Management and External Wallets
3.1 Default Key Storage Model
By default, Canton node-level operational keys are generated and stored within the participant’s database as part of the standard Canton node configuration. This approach is sufficient for many deployments and aligns with Canton’s out-of-the-box security model.
3.2 Key Management Service (KMS) Integration
A Key Management Service (KMS) is an external system for generating, storing, and protecting the cryptographic private keys that Canton Validator nodes use for signing transactions and establishing their identity on the network. Instead of keeping these keys inside the validators’s own database, a KMS externalises key storage so that private key material never resides in application infrastructure, giving you hardware-backed, audited, and centrally-managed key custody.
Canton natively supports KMS integration and offers two modes of operation:
Encrypted private key storage — keys remain stored inside Canton’s database but are encrypted at rest using a KMS-managed wrapper key (also referred to as envelope encryption).
External key storage — keys are generated and stored entirely within the KMS. Canton never holds the raw private key material; all cryptographic operations are delegated to the KMS.
For more background on how Canton handles these two modes, see the Digital Asset documentation:
3.2.1 KMS Configuration in CatalyX Blockchain Manager
CatalyX Blockchain Manager supports environment-level KMS configuration for Validator nodes. When enabled, all newly created validators in the environment are provisioned with KMS-backed validator keys. Validators already deployed without KMS are not affected — their configuration remains unchanged.
KMS is disabled by default and is opted into via Operator environment variables. For prerequisites, configuration steps, verification guidance, and current scope and limitations, see the dedicated KMS Integration page:
Key Management Service (KMS)For detailed guidance on configuring Canton with a specific KMS provider (AWS, GCP, or a custom driver), refer to the Digital Asset documentation:
3.3 Advanced Security Hardening
For deployments requiring stronger key-protection guarantees beyond the standard KMS integration, an Azure KMS driver can be implemented to integrate Canton with Azure Key Vault. In this model:
Node-level operational keys are generated and stored in Azure Key Vault instead of the participant database
Keys are managed as customer-managed keys (CMKs) Private key material is handled by Azure Key Vault and never exposed in plaintext
Deployments can leverage FIPS 140-2 compliant cryptographic modules available in Azure Managed HSM
This approach enables centralized key management, stronger isolation of cryptographic material, and alignment with enterprise and regulatory security requirements.
3.4 Integration with Wallet-as-a-Service Providers
Our solution supports integration with Wallet-as-a-Service (WaaS) providers such as Dfns, enabling secure and compliant management of cryptographic keys without requiring organizations to operate their own key infrastructure.
Validators can be registered directly with a WaaS, and subsequent Wallets (external parties) can be created through the WaaS interface. Instead of handling private keys locally, all cryptographic operations (e.g., signing, authentication) are delegated to the WaaS, ensuring that keys never leave the secure environment.
Key storage is managed by the WaaS in a distributed, zero-trust architecture, with an optional configuration to leverage Hardware Security Modules (HSMs) for additional protection and compliance with industry security standards (FIPS 140-2/3, Common Criteria, etc.).
This approach provides:
Enhanced Security: Private keys are never exposed to application code or infrastructure.
Operational Resilience: WaaS ensures redundancy, access control, and secure recovery.
Regulatory Compliance: HSM-backed storage satisfies stringent regulatory and audit requirements.
Seamless Integration: Validators and external parties can be provisioned through the same WaaS API, simplifying lifecycle management.
By offloading key custody and signing operations to a WaaS, organizations gain a secure and scalable way to operate validators and external parties, reducing the risk of compromise while maintaining full control over their operational workflows.
3.5 Strict Key Usage Policies
KMS key policies restrict usage exclusively to the Kubernetes IAM roles associated with the tenant’s Canton workloads.
No human IAM user is granted direct permissions to perform kms:Decrypt or kms:Sign operations on node operational keys.
3.6 Access Control & Monitoring
All Azure Key Vault operations are fully logged
Quarterly access reviews are performed as part of the security governance process.
Multi-factor authentication (MFA) is enforced for all Azure console users, with operational key usage being fully automated and non-interactive.
4. Privacy Controls
4.1 Security Logging & Monitoring
Objective: Ensure comprehensive security monitoring, forensic log retention, and 24/7 incident response readiness.
Centralized Log Repository: Deployed a dedicated Azure Log Analytics Workspace (law-canton-[env]-law).
Retention Policy: Enforced at 30 days for Mainnet (Production) and 7 days for Devnet/Testnet to meet forensic investigation requirements.
Control Plane Audit Trail: Enabled Azure Activity Logs streaming at the subscription level. This guarantees an immutable record of all infrastructure changes, role assignments, and policy modifications.
Data Plane Audit Trail: Automated Diagnostic Settings for all critical resources.
AKS: Capturing kube-audit and kube-apiserver logs to track internal Kubernetes API interactions.
PostgreSQL: Configured the pgaudit extension to track database sign-ins and query execution.
Networking: Configured to capture flow logs.
SIEM & MSSP Integration: Fully onboarded Microsoft Sentinel. The environment is integrated with the Microsoft Defender Unified Security Operations Platform and is Azure Lighthouse-ready, enabling secure, credential-less 24/7 monitoring by an external MSSP.
4.2 User Consent and Access Logs
System access is logged with user context from Keycloak. These logs support compliance with data protection laws and enable investigations and traceability in the event of an incident
Last updated
Was this helpful?