Encryption and key management for Apache Fineract

Encryption and key management for Apache Fineract: where the keys sit and who holds them

A bank or lender running Apache Fineract in infrastructure it controls needs an encryption design it can defend to auditors, and the starting point is knowing which layers the platform covers and which ones the deployer must build. Fineract's documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. It recommends PostgreSQL as the database and describes tenant connections being loaded from a tenants database. Beyond those documented items, encryption at rest for the database and backups, encryption of uploaded client and KYC documents, and the management of keys and secrets are largely the deployer's responsibility. Treat the platform as providing transport settings and nothing more until your own design says otherwise.

Teams need this work at three points: before production go-live, when a new tenant is onboarded with its own database connection and credentials, and when an auditor or internal risk function asks how data is protected. Each of these moments creates keys and secrets that must have an owner, a storage location, a rotation process and a recovery path. Write that inventory down early, listing the TLS certificates for each hop, the database credentials for write, read and batch instances, the tenant master password, backup encryption keys and document storage keys. Confirm with your platform team which of these your chosen PostgreSQL service, storage platform and Kubernetes setup can already encrypt, and which need configuration you own.

The design question that follows is who holds each key and where it is kept. A secrets manager or key management service can hold application secrets, issue certificates and perform encryption operations, but it becomes a critical dependency for the whole Fineract estate, so its own availability, access model and backup need the same scrutiny as the core banking system. Decide whether the key service runs inside your infrastructure, whether a managed service is acceptable under your outsourcing and data residency rules, and which team can approve key access. Those decisions determine how the rest of this topic is built.

Where TLS belongs on every hop in a Fineract deployment

Every network hop that carries customer, account or credential data should use TLS, and the client-facing hop is the one the Fineract documentation addresses directly. The project strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Enable TLS at the edge, decide whether traffic is re-encrypted between the gateway and Fineract, and confirm in the Fineract documentation at the platform documentation which SSL variables your release reads, since names can differ between versions. Browser and mobile clients should never reach a plain HTTP listener, and the gateway should refuse downgrade attempts.

The internal hops need the same decision made explicitly. Fineract to PostgreSQL carries account data and database credentials, so the connection should be encrypted and the server certificate verified by the application, not just accepted. Fineract to a message broker carries external business events such as ClientCreated, which are disabled by default, so enable TLS on the broker listener before turning events on. Write, read and batch instances, along with any remote partition workers coordinated through ActiveMQ or Kafka, exchange data across the cluster, so treat them as hops too. Admin consoles, metrics endpoints and log shippers often use separate ports and are frequently left in plain text; list each one in your design and confirm its TLS setting.

Certificate issuance, renewal and rotation depend on how you deploy: containers, Kubernetes, a virtual machine image or a managed cloud load balancer each handle trust stores and secret mounts differently. Confirm with your chosen deployment method and your platform team who issues certificates, how often they renew, how a rotation reloads running instances, and whether a restart is needed. Ask your PostgreSQL and broker vendors how they expect clients to validate certificates. Keys and certificate material should be stored and rotated under the controls described in the rest of this page, not copied into images or environment files.

Encryption and key storage options and when each fits

This table compares the encryption layers and key storage options for a self-hosted Fineract deployment, from TLS and database encryption to KMS, Vault, OpenBao, Infisical and Kubernetes secrets. Read each row as a decision: find the layer you need to protect, then check when the option fits and what your team must confirm before choosing it. The main takeaway is that licensing, Enterprise-only features and your existing cloud footprint often decide the key store more than technical fit.

Option	When it fits	What must be confirmed
TLS termination at gateway or ingress	Clients reach Fineract through a gateway or Kubernetes ingress that can hold certificates and enforce HTTPS only	Whether traffic between the gateway and Fineract pods is also encrypted, and how the SSL settings through FINERACT_SERVER_SSL_ENABLED are applied
PostgreSQL encryption in transit	Fineract, its read instances and batch instances connect to PostgreSQL across a network you do not fully control	That the PostgreSQL server enforces TLS, that the JDBC connection string requires it, and that certificate validation is set rather than skipped
PostgreSQL encryption at rest	Your storage layer or database platform offers volume or tablespace encryption and your policy requires it for customer data	Whether encryption covers the data volume, WAL archives and replicas, and where the keys live
Backup encryption	Backups of the Fineract and tenant databases leave the primary site or are held on object storage	Who holds the backup keys, whether restores have been tested with those keys, and how keys are rotated without losing old backups
Document storage encryption	Client KYC documents and loan files are stored on object storage or a file system outside the database	Whether the storage service encrypts objects at rest, who can read the keys, and whether encryption is applied before upload
Cloud KMS	Your workloads already run in one cloud and you want keys managed by that provider's service with native IAM controls	Which regions and services the KMS covers, how key policies map to your staff roles, and the provider's own audit logging
Self-hosted OpenBao	You need Vault-style secrets, dynamic credentials and PKI inside infrastructure you control under an MPL-2.0 license	That your migration guide version matches your deployment, since its migration guide was tested only against Vault 1.14.1 community edition
HashiCorp Vault	Your organization accepts the Business Source License 1.1 terms and needs Enterprise features such as HSM support or FIPS compliance	Which Enterprise features require a license on the cluster, the current license terms with IBM as licensor, and the quoted commercial model from sales
Infisical	Teams want secrets, PKI and a KMS in one tool with a Kubernetes operator, and can run it under MIT terms outside the ee directory	That SSO and gateways are included in your self-hosting license, and that you have reviewed the ee/LICENSE terms for any enterprise code you deploy
Kubernetes secrets	Only for non-sensitive configuration or as a delivery mechanism fed by an external store	Whether etcd encryption at rest is enabled on the cluster and who can read secrets through the API or service accounts

Choosing a KMS or secrets manager by operating model

If your Fineract deployment already runs in a cloud provider's account, the provider's key management service is usually the shortest path to encryption at rest for database volumes, backups and object storage. Keys stay inside the account boundary, access follows the cloud identity model your auditors already review, and the provider runs the key infrastructure. The trade-off is that application secrets such as database passwords, tenant credentials and API tokens still need a separate home, and the design becomes harder to move as workloads bind more deeply to one provider.

Key custody: Confirm which roles can change key policies and whether those roles overlap with the people who administer the database or backups.
Rotation: Check whether automatic key rotation covers the keys you use, and plan application secret rotation separately, because key rotation does not rotate passwords stored in Fineract's configuration.
Audit: Ask whether key operations are logged to the same trail as other access events and how long those logs are retained for examiners.
High availability: Confirm the regional design of the service and how backup restores decrypt during a regional outage.
Cost model: Ask the provider how key storage, key operations and log volume are billed, since these recur with usage.

Check that your cloud account already has a documented key policy for each data class that Fineract stores.

Setup sequence for encryption and key management

This sequence moves a Fineract deployment from an unmapped set of data stores to encrypted transport, encrypted storage and backups, and runtime secret delivery, with a check at each stage. The output is a documented key hierarchy, a running secrets manager or KMS, and restore-tested backups that you can hand to your security and audit teams.

Inventory data stores, documents and secrets
Your platform or security engineers list every place Fineract holds data or credentials: the PostgreSQL primary and read replicas, the tenants database, backup targets, document storage used for client and KYC files, message brokers if business events are enabled, and every credential Fineract and its supporting services use. For each item, record the data classification, the network path it crosses and the owner. The step is done when the inventory has no unnamed store and each row names an owner. Confirm with your Fineract configuration which external event publishing and document storage options are actually enabled in your environment.
Define the key hierarchy and ownership
Decide which keys protect which data, who can create, rotate and revoke each key, and which team holds break-glass access. A common layout separates the root key held by the secrets manager or KMS, the data encryption keys used by the database and backup tooling, and the application secrets Fineract reads at runtime. Write this as a short document signed off by security and the data owner. The check is a table where every store from step one maps to exactly one key or key class and one accountable owner.
Deploy the secrets manager or KMS separately
Install the chosen secrets manager or KMS in its own failure domain, with its own database, backups and network policy, so that a Fineract outage or a compromised Fineract node does not take the key service down with it. Options include self-hosted Infisical, which provides secrets, a KMS, a private PKI and dynamic database credentials, and HashiCorp Vault or OpenBao, which have their own licensing and feature trade-offs to review before you commit. Confirm the license terms for any enterprise features you need, such as SSO or gateways. The check is a successful health check, a tested unseal or recovery procedure and an access log entry for a test read.
Issue and install TLS certificates on every hop
Issue certificates from an internal or public certificate authority for the gateway, the Fineract read and write instances, the batch instance, the database connection and any broker or front-end connection, then configure Fineract to serve HTTPS only using the SSL settings in its documentation, such as FINERACT_SERVER_SSL_ENABLED. Set a certificate renewal process before the first expiry. The check is an external TLS scan of the gateway showing the expected chain, plus a verified connection from each Fineract instance to the database that rejects an untrusted certificate.
Enable and verify database encryption at rest
Turn on encryption for the PostgreSQL volumes or storage layer using your platform's supported mechanism, and confirm that the keys come from the KMS defined in step three. Encryption at rest protects the disk and snapshots, so you still need access control and TLS in front of the database. Test by reading a row from a volume snapshot in an isolated account and confirming the data is unreadable without the key. Ask your database team to confirm the approach against the PostgreSQL version you run. The check is a documented encrypted-volume record and a failed read from an unkeyed copy.
Configure encrypted backups and test restores
Encrypt every database dump, WAL archive and document backup before it leaves the production network, using keys held in the KMS and not stored beside the backup. Keep the backup encryption key separate from the data key so that a restore needs a deliberate key release. Run a restore into an isolated environment, start a Fineract instance against it and confirm that the tenant data loads and that the end-of-day process reads correct balances. Record the restore time you observe. The check is a signed restore test report that names the backup, the key used and the verified tenant.
Fetch secrets at runtime without baking them into images
Configure Fineract and its supporting services to read database passwords, the tenant master password, OAuth client secrets and document storage credentials from the secrets manager at startup, using an agent, Kubernetes operator or platform identity such as the cloud workload identity your team already runs. Remove every credential from container images, Helm values files and source control, and scope each machine identity to the one secret it needs. The check is a scan of the built image and the repository finding no secret values, plus a log entry showing each service fetched its own secrets only.
Rotate keys and secrets on a documented schedule
Write a rotation procedure for each key class from step two, covering who approves the change, the order of operations (new key issued, services reloaded, old key retired after confirmation), and the rollback path. Rehearse one rotation of the database credential and one of a backup key in a non-production copy before you run it in production. Dynamic database credentials, where the secrets manager supports them for your database, reduce the number of long-lived passwords. The check is a completed rehearsal log showing Fineract instances reconnected after rotation with no failed transactions and the old credential rejected.

Security and operational risks to control

Encryption for Fineract depends on keys and secrets that must stay available, traceable and rotatable while the platform keeps running. The cards below cover the failure modes that most often turn a sound encryption design into a production outage or an unrecoverable data loss.

Key custody and break-glass access

Decide who can read the master keys and tenant secrets, and how an emergency path works when the normal identity provider or secrets manager is unreachable. Keep break-glass credentials sealed, split between named custodians, and tested on a schedule. Confirm that using the break-glass path raises an alert and creates a review record, and that the path does not depend on the same systems it is meant to recover. Write the custody procedure before go-live, not during an incident.

Secrets manager as a single point of failure

If Fineract fetches database, tenant and TLS secrets at startup, an outage of the secrets manager can stop new pods from starting and block restarts of running ones. Plan high availability for the secrets platform itself, its database and its storage backend, and confirm which secrets are cached locally and for how long. Ask the vendor or platform team which backend is officially supported for your chosen version before you commit to an architecture.

Certificate expiry

TLS certificates on the gateway, the Fineract write and read instances, the batch instance and any broker or database connection will expire on different dates. An expired certificate on one hop can fail login, reporting or the end-of-day batch without a clear error. Track every certificate in an inventory, automate issuance and renewal where the private PKI or ACME supports it, and alert well before expiry. Confirm how each Fineract instance reloads a renewed certificate.

Backup key loss

Backups encrypted with a key that is lost, deleted or left only in a retired secrets store make the data unrecoverable, even if the database files are intact. Keep backup encryption keys in at least one location separate from the backed-up data, record which key version encrypted each backup, and keep old versions until every backup they protect has expired. Test restores from a clean environment using only the documented key recovery steps.

Logging of secret reads

Every read of a database password, tenant secret or signing key is a privileged event. If the secrets platform does not record reads, a compromised workload or operator can extract credentials without a trace. Enable audit logging on the secrets manager, forward it to your SIEM, and alert on reads from unexpected identities or outside deployment windows. Check that secret values never appear in Fineract logs, container images or CI output.

Rotation without downtime

Rotating a database or tenant secret can break running instances, and the timing is constrained by Fineract's own operations. Liquibase migrations run only on write instances, so a credential change on the write path needs a planned window, while the Close of Business Day batch job can run for hours and should not be interrupted mid-run. Schedule rotations outside batch windows, use dual-valid credentials during the change where the database supports it, and confirm with the project's documentation how each instance type picks up new values.

Questions buyers ask about encrypting Fineract

What drives the cost and effort of encrypting a Fineract deployment?

The biggest drivers are how many hops carry data, how many stores hold sensitive material, and how many keys and secrets must be moved under control. A deployment with a gateway, a PostgreSQL primary and read replicas, a batch instance, document storage and a backup target has more encryption points than a single-node test system. Costs have two parts: the implementation work (certificate issuance, TLS configuration, database and backup encryption, secret migration) and any licensed key manager you choose. Ask any quote to list each encryption point, who configures it, and which items recur, such as certificate renewal and key rotation.

How long does encryption work take, and what changes the duration?

Duration depends on the number of encryption points and on how much of the environment already has a working certificate authority, secrets store and backup tooling. Work goes faster when the platform team already runs TLS and a KMS, and slower when keys are stored in configuration files or when the backup system cannot encrypt without re-architecture. No timeline is stated here because none has been supplied for this work. Ask for a written schedule that separates the design phase, the staging test, the production cutover and the first rotation cycle.

What does the client's team need to provide for this work?

The engagement needs access to the environment and people who own each layer. Expect to provide a named owner for DNS and certificate issuance, the database administrator for PostgreSQL encryption settings, the backup administrator, and whoever approves key custody. You will also need a staging copy of the deployment where configuration changes can be tested before production. Confirm early which secrets currently exist in environment variables, images or source control, because removing them usually needs a change window.

Can an internal team encrypt Fineract without outside help?

Yes, if the team already operates PostgreSQL, TLS and a secrets platform and has time to test restores. The work is mostly configuration and verification rather than new code, but mistakes are costly: an expired certificate or a lost key can stop writes or make backups unreadable. Teams without recent experience with key rotation often benefit from an outside review of the design before cutover. Whatever the choice, document who can read keys, how they are recovered and how the team proves the setup works.

Which key manager should we choose, and what licensing should we check?

Choose based on the features you need and the license terms that will apply to your deployment. Infisical's repository is MIT Expat licensed, except content in any ee directory, which uses a separate license, and its self-hosting documentation says that features such as SSO or gateways require enterprise licensing. HashiCorp Vault moved future releases to the Business Source License 1.1 under a license naming IBM as licensor, and Vault Enterprise features such as HSM support, FIPS compliance and seal wrapping need a license applied to the cluster. OpenBao is an MPL-2.0 fork whose migration guide was tested only against Vault 1.14.1 Community Edition. Confirm the license file for each version you plan to run, and ask vendors for their current commercial terms in writing.

How does encryption affect backups and restores?

Encrypted backups are only useful if the keys needed to decrypt them can be recovered on a clean system. Before go-live, test a full restore into an isolated environment using only the documented key recovery path, not the live key manager. Keep the backup encryption keys separate from the data they protect, and record which key version each backup uses so that rotation does not orphan older archives. Ask for restore timing and key recovery steps to be part of the acceptance test, since a backup that cannot be decrypted during an incident provides no protection.

Will the key manager be a single point of failure for Fineract?

It can be, if Fineract and its database need the key manager to start or to read configuration during every request. Design for failure by deciding which secrets are fetched at startup, how long cached values remain valid, and what happens when the manager is unreachable during a restart. For Vault-style deployments, the storage backend and seal configuration determine recovery, and HashiCorp recommends integrated storage (Raft) for most use cases. Ask the implementer to show the failure modes in a test and to document the break-glass procedure.

How encryption and key management run after go-live

Encryption at go-live is a starting point. The ongoing work is keeping certificates valid, rotating keys on a schedule you can defend, proving that encrypted backups restore, and watching the secrets manager for signs of trouble. Assign an owner for each item before launch. Certificates for the public API edge, the Fineract instances and any internal hops should sit in one inventory with expiry dates, and the renewal process should be tested in a non-production environment at least once. Confirm with your certificate authority and your load balancer or gateway how renewal is triggered and whether reloads drop connections, since a missed renewal on a banking API stops payments and logins at the same time.

Key rotation needs a written schedule for each class of secret: the database credentials Fineract uses for its write, read and batch instances, the tenant connection secrets held in the tenants database, the keys used to encrypt backups and document storage, and the credentials your integrations use to fetch secrets. Rotation of the tenant master password and of encrypted tenant schema passwords needs its own runbook, because a change applied to one instance and not another can leave the platform unable to connect. Restore tests matter as much as rotation. Run a periodic restore of an encrypted backup into an isolated environment, confirm the key material needed to decrypt it is available to the recovery team without the original administrator, and record the result as evidence.

Access reviews and monitoring close the loop. Review who can read, write, rotate and approve access to the secrets manager, and remove standing access that no longer matches a role. If you run Infisical, Infisical's self-hosting overview lists which enterprise features, such as SSO or gateways, need a license, so confirm those before you rely on them in reviews. Alert on failed secret fetches from Fineract pods or services, because repeated failures can mean an expired credential, a revoked machine identity or an attacker probing access. Finally, treat every Fineract upgrade and every database platform change as a configuration event. Retest TLS settings such as FINERACT_SERVER_SSL_ENABLED, secret sources, Liquibase runs on write instances and restore procedures after each move, because a new release or database version can change what the platform expects.

How DeployOpen scopes and delivers Fineract encryption work

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For Fineract encryption, we start from a written scope that names every connection, datastore, backup and secret store in your deployment before any configuration changes are made.

How we scope

Map every Fineract network hop, including gateways, application instances, PostgreSQL primaries, replicas and batch workers.
List every datastore that holds client data or documents, including backups, logs and exported reports.
Agree in writing which key management or secrets platform will hold keys, who administers it and where it runs.
Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.

How we build

Configure TLS on each hop using the SSL settings Fineract exposes through environment variables, then verify certificate chains.
Enable database and backup encryption at rest and test restores from encrypted backups before go-live.
Move tenant and integration credentials out of images and source control into the secrets store chosen during scoping.
Test encryption settings in a non-production copy and record the results for your security and compliance teams.

How we hand over

Deliver a runbook covering key creation, rotation, revocation, access approval and recovery procedures in your environment.
Document every encrypted component, its key owner and the configuration keys that control it, for your audit file.
Walk your platform, security and operations staff through rotation and break-glass steps and record who attended.
Provide evidence of configuration and test results, while your independent auditors determine whether controls meet any requirement.

How we support

Ongoing support, upgrades and continuous testing are available as retainers, scoped separately from the build.
Retainers can cover key rotation cycles, reviews of new Fineract releases and changes to encrypted components.
Agree with us in advance how emergency key changes are handled and who approves them at your organization.
Confirm retainer terms, response expectations and included activities in writing before the service begins.

Encryption and key management for Apache Fineract