Skip to main content
The CRM plugin manages sensitive, identity-related data. Using it well means going beyond basic setup — it takes thoughtful integration, disciplined data handling, and solid operational practices. These recommendations complement the CRM data security guide, which covers encryption, hashing, and key management in detail.

​
1. Follow the correct integration flow

CRM relies on a specific entity creation order. Skipping steps or creating entities out of sequence can lead to broken integrations and missing data downstream. The expected flow is:
  1. Create the Holder — representing the individual or organization.
  2. Create the Alias Account — linking the Holder to a Midaz Ledger account.
  3. Verify both — before proceeding with any downstream flows.
Without a Holder linked to an Alias Account, most CRM-driven features (fees, notifications, billing, identity verification) won’t work as expected.
The CRM API does not validate the accuracy of the data you submit. Supplying incorrect identifiers (like a mismatched ledgerId or accountId) may cause integration failures with the Ledger or other plugins. Always verify your identifiers before creating records.

​
2. Protect your encryption keys

CRM encrypts and hashes sensitive fields before storing them. The security of this data depends entirely on how you manage your keys.
  • Generate unique keys for LCRYPTO_HASH_SECRET_KEY and LCRYPTO_ENCRYPT_SECRET_KEY using openssl rand -hex 32.
  • Store keys in a secret manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, or equivalent). Never hardcode them in configuration files, source code, or version control.
  • Plan for key rotation. If a key is compromised, you must generate a new one and re-encrypt all affected data. This is a manual process — design your operational runbooks accordingly.
  • Use Kubernetes Secrets in production. Reference existing secrets via useExistingSecret and existingSecretName in your Helm values instead of storing keys inline.
For the full list of protected fields and encryption strategies, see CRM data security.

​
3. Never store sensitive data in metadata

The metadata object in CRM entities is not encrypted. It’s stored in plain text and intended for non-sensitive, auxiliary information only. Do not use metadata for:
  • Personal identification numbers (CPF, SSN, passport)
  • Financial account details
  • Contact information (email, phone)
  • Any data subject to LGPD, GDPR, or similar regulations
If you need to store a sensitive attribute that isn’t in the protected fields list, contact your Lerian representative to discuss options.

​
4. Do not expose CRM directly on edge layers

CRM is an internal service. Exposing it directly through API gateways, load balancers, or frontend applications increases your attack surface and bypasses application-level access controls. Instead:
  • Route CRM traffic through your backend services or an internal API layer.
  • Use Access Manager to enforce authentication and authorization if you need fine-grained control.
  • Restrict network access to CRM pods using Kubernetes NetworkPolicies or your cloud provider’s security groups.

​
5. Use soft delete as the default

CRM supports both soft delete and hard delete:
  • Soft delete (default): Marks the record with a deletedAt timestamp. The record is excluded from standard queries but remains in the database for audit and recovery purposes.
  • Hard delete: Permanently removes the data with no possibility of recovery.
For most use cases, soft delete is the safer choice. It preserves audit trails and allows recovery if data is deleted by mistake. Reserve hard delete for scenarios where regulatory requirements demand complete removal (e.g., GDPR right to erasure requests).

​
6. Validate data before sending it to CRM

CRM acts as a neutral, persistent data layer. It doesn’t enforce business rules, validate document formats, or check KYC compliance. Data integrity is your responsibility. Before creating or updating records:
  • Validate document formats (CPF, CNPJ, passport numbers) on your application layer.
  • Ensure ledgerId and accountId values correspond to real entities in Midaz.
  • Sanitize inputs to prevent storing malformed or inconsistent data.

​
7. Keep CRM and Midaz versions aligned

The CRM plugin is versioned together with Midaz Core. Before upgrading:
  • Check the version compatibility table to confirm your target versions are compatible.
  • Always upgrade Midaz Core first, then CRM.
  • Test the upgrade in a staging environment before applying it to production.
  • Back up your MongoDB data and Helm values before any major upgrade.
For upgrade procedures, see the Helm upgrade guide.

​
8. Monitor database health and performance

CRM uses MongoDB for data storage. In production environments:
  • Monitor connection pool usage. The default MONGO_MAX_POOL_SIZE is 1000. Adjust it based on your traffic patterns and replica count.
  • Set up alerts for MongoDB disk usage, replication lag, and connection saturation.
  • Enable backups. Whether you use the bundled Bitnami MongoDB or an external instance, ensure automated backups are in place and tested regularly.
  • Enable OpenTelemetry (ENABLE_TELEMETRY: true) to collect traces and metrics from CRM. Integrate with your observability stack for end-to-end visibility.

​
9. Review the security recommendations

CRM handles personal and sensitive data. Beyond plugin-specific practices, make sure your deployment follows the platform-wide Security recommendations, which cover:
  • Network segmentation and Zero Trust Architecture
  • TLS 1.2+ enforcement for all communications
  • IAM and RBAC configuration
  • Incident response planning
  • Patch management and vulnerability scanning