Why Apache Fineract tenant database passwords need encryption outside the image
The goal is to keep tenant and read-only schema passwords encrypted at rest, protected by a master password that lives in a secrets store, never in a container image, a Helm values file or a Git repository. A leak of the tenants database should expose nothing that connects to a client or loan schema without also compromising the master password.
Apache Fineract is multi-tenant. According to the README, API requests carry a Fineract-Platform-TenantId header, and each tenant's database connection is configured from a tenants database. That means one credential store sits behind every tenant, so a single exposed row can reach one institution's client records, KYC references and loan data. A leak in a multi-tenant deployment is therefore a cross-tenant incident, not a single-customer one, and the planning should assume that. Ask who can read the tenants database, which service accounts connect to it, and whether backups of that database are encrypted separately from the application data.
Confirm the exact property names, the encryption algorithm and the behavior of the master password against the Fineract 1.15.0 documentation for your chosen deployment method (container, Kubernetes or a custom build), before writing any configuration. Do not assume that a value stored in the tenants database is encrypted until a test instance proves it, and check how the master password is supplied at startup and whether it is cached in logs or environment listings. The Apache Fineract platform documentation is the starting point for that verification.
Where the tenant master password can live and when each option fits
This table compares five places to keep the Fineract tenant master password and the secrets it protects, from a Kubernetes secret to a managed key service. Read each row for who operates the option, what it guards against, the licensing or commercial model to confirm, and whether it works in air-gapped or data-center networks. The main takeaway is that the choice depends on who must operate the key store and whether the network can reach an external service.
| Option | Who operates it | What it protects against, and licensing to confirm | Fit for air-gapped or data-center deployments |
|---|---|---|---|
| Kubernetes secret injected at runtime | Your platform team, through the cluster's secret handling | Keeps the password out of images and source control, but protection depends on cluster encryption at rest and RBAC. No separate license applies. | Good fit when the cluster runs inside your network. Confirm how etcd encryption is configured. |
| Self-managed OpenBao cluster | Your security or platform team, with no vendor-run service | Encrypts secrets before storage and supports leasing and revocation. Licensed under MPL-2.0; confirm the version you deploy and its support model. | Strong fit. Runs entirely on servers you control, with integrated storage or PostgreSQL as the HA backend. |
| Self-managed Vault Enterprise cluster | Your team operates the cluster; HashiCorp provides the licensed Enterprise features | Similar secret protection to OpenBao, plus Enterprise features such as FIPS compliance and HSM support. Licensed under the Business Source License 1.1 for 1.15.0 or later; Enterprise pricing is through sales. | Workable in data centers. Enterprise features need a license applied to the cluster, so confirm licensing terms for disconnected networks. |
| HCP Vault Dedicated | HashiCorp operates the managed service | Runs the same binary as self-managed Vault Enterprise. Ask for the service terms, the data location and the commercial model in writing. | Poor fit for strictly air-gapped networks, because the service is hosted outside your environment. Confirm connectivity and data residency. |
| Cloud key management service | Your cloud provider operates the key service; your team manages key policy | Protects keys with provider-managed hardware and access logging, but stores secrets under that provider's control. Confirm pricing and terms with the provider. | Limited fit for air-gapped or on-premises deployments, which must run without a public cloud dependency. |
Which secrets to encrypt: master, tenant, read-only and migration credentials
A Fineract deployment holds several database credentials, and each one opens a different slice of data. Listing them by blast radius and runtime need tells you which ones must be encrypted, which must be scoped down, and which should never reach a running container at all.
Tenant master password
The master password protects the tenants database, which holds the connection details for every tenant. Whoever can read it can reach every tenant schema, so its blast radius is the whole platform. It is needed at startup by instances that resolve tenant connections, and should be encrypted at rest, kept out of images and source control, and rotated under a documented procedure. Confirm how your build reads it before you choose a secret store.
Tenant write schema credentials
Each tenant has a write schema credential that lets the application change loan, savings and ledger data for that tenant. A leak exposes one tenant's full transactional record and the ability to post changes to it. Write instances need this credential at runtime, so limit it to the write role, store its encrypted form in the tenant record, and check that no other instance type loads it.
Read-only schema credentials
Read instances serve reporting and query traffic, usually from database read replicas. Their credential should carry read-only privileges, so a compromised read node cannot alter balances or journal entries. Confirm the separation of read and write credentials against the instance type settings in the Fineract documentation before you assume the read tier is protected by database privileges alone.
Batch instance credentials
Batch instances run scheduled jobs such as the Close of Business Day process, which can run for hours on large portfolios. They need write access to every tenant they process, which makes their credential as sensitive as the write credential. Restrict batch nodes to the network paths they need, and review which tenants each batch credential can reach.
Database administrator and migration accounts
Liquibase migrations change schema structure, so the account that runs them needs DDL rights that no runtime instance should hold. Keep this account out of the application's environment variables, run migrations through a separate job such as the liquibase-only profile, and retire the credential once the change is applied. Ask your DBA team who holds it and where it is logged.
Backup and export credentials
Backup jobs and data exports read complete copies of tenant data, so they can expose everything the database holds even when no application credential is compromised. Use dedicated accounts with read-only access, encrypt backup storage separately, and rotate these credentials on their own schedule. Confirm with your backup tool and storage provider how keys for encrypted backups are held and recovered.
Setting up encrypted tenant credentials step by step
This sequence moves Fineract tenant, schema and migration credentials out of images, source control and plain configuration, and into a secrets store that the runtime identity alone can read. Each step ends with a check you can record as evidence.
Inventory every tenant and schema credential
The platform team and the database administrator list every credential Fineract uses: each tenant entry in the tenants database, the read-write and read-only users for each tenant schema, the Liquibase migration user, and the users behind the write, batch and read instances. For each one, record the owner, the systems that consume it, and where it is stored today, including any copies in CI variables, Helm values, container images or chat logs. The output is a credential register that security signs off on before any change is made.
Choose and deploy the secrets store
Decide between HashiCorp Vault and OpenBao, weighing the license terms (Vault moved to the Business Source License for newer releases, while OpenBao is MPL-2.0), the Enterprise features you need, and your support model. Confirm the license position with your legal team before you deploy. Deploy the cluster with a highly available storage backend, integrated storage (Raft) for most deployments, and confirm that you can initialize, unseal and back up it. The check is a healthy cluster with a tested backup and a documented unseal procedure.
Create the master password with narrow access
Write the tenant master password to a dedicated secrets path, then create a policy that grants read access only to the identity the Fineract runtime uses. For servers, AppRole is the method OpenBao recommends, and Kubernetes pods can authenticate through the Kubernetes auth method. Administrators keep write and rotation rights but no standing read access. The check is a test login as the Fineract identity that reads the secret successfully, followed by denied reads from other identities, including the CI system and developers.
Configure Fineract to read secrets at startup
Inject the master password into the Fineract process environment at startup, using your orchestrator's secret integration or the secrets store agent, so that the image and the deployment manifests contain no secret values. Confirm the exact environment variable names for your Fineract release in the platform documentation before you write them into manifests. The check is that a running container shows the variable populated when inspected by the runtime identity, while the manifest in Git contains only a reference to the secret.
Encrypt tenant and read-only passwords as required
Confirm with the Fineract documentation and release notes for your version which tenant and read-only password fields are stored encrypted, how the master password is applied to them, and which fields still need to be set through a supported step. Set each password through the supported mechanism, then record which entries are encrypted and which are not. The check is a query against the tenants database for the known test values, which should return no plaintext matches for any field the documentation says is encrypted.
Run migrations with separate credentials
Liquibase migrations run only on write instances, and on Kubernetes they can run as a separate job using the liquibase-only Spring profile. Give that job its own database user with schema-change rights, and give the runtime users only the data privileges they need. Deploy the migration job before the write instance starts, and keep the job's credential in the secrets store alongside the runtime credentials. The check is a completed migration job, plus a failed attempt by the runtime user to alter a table, which confirms that the separation holds.
Verify images, Git history and tenant connections
Scan every image layer and build cache for the known secret values, and scan the Git history across all branches and tags with a secret-detection tool. If a value is found in either place, treat it as exposed, rotate it and rewrite or retire the affected artifacts. Then test each instance type: connect the write and batch instances, and each read instance against its replica, for every tenant using the Fineract-Platform-TenantId header. Record the results with the image digest and commit hash, so the evidence can be reviewed later.
Document and rehearse master password rotation
Write a rotation runbook that covers generating a new master password, updating the secrets store, handling the tenant password changes that depend on it, restarting or rolling the instances in a defined order, and revoking the old value. Confirm with the Fineract documentation for your release whether a master password change requires re-encrypting stored values, and plan that step explicitly. Rehearse the procedure in a non-production environment first. The check is a rehearsal record showing that every instance type reconnected and that the old value no longer works.
Rotating the master password without taking tenants offline
Rotating the tenant master password is harder than changing one secret, because the master password is the key that protects every encrypted tenant credential beneath it. Each tenant's database password and read-only schema password must be re-encrypted under the new master password before the old one is retired, so the order of operations decides whether tenants keep connecting. Plan the rotation as a sequence: confirm the current state of every tenant record, prepare the re-encrypted values, switch the running instances to the new key, and only then remove the old key from the deployment. Confirm the exact re-encryption procedure and any supported key-change steps in the Fineract 1.15.0 documentation before writing runbooks, since the project's own instructions govern what the tenants database accepts.
Run the rotation as a rolling change across the instance types the Fineract documentation describes: read, write and batch. Liquibase migrations run only on write instances, so keep the write and batch nodes on a known version during the window and restart read instances first, then batch, then write, checking tenant connections after each step. Keep the previous master password and the prior tenants database snapshot available until every tenant has connected successfully under the new key. If a tenant fails to connect, roll back that instance to the old master password, restore the saved tenant record if it was changed, and investigate before continuing. Test this entire sequence in a staging copy of the tenants database first, with the same number of tenants and the same instance layout as production.
Secrets store lease and rotation features differ between products, so confirm them for OpenBao or HashiCorp Vault before finalizing the design. Check whether the chosen product can rotate the master value without a restart, how it versions secrets, whether it supports the dynamic or leased credentials you need for tenant database accounts, and what licensing applies to the features you rely on. The OpenBao migration guide and the Vault Enterprise documentation are the natural next reads for those checks, and both should be confirmed against your chosen version.
Choosing a secrets approach by hosting environment
On Kubernetes, the usual pattern is to keep the tenant master password in an external secrets store and sync it into the pod at runtime, rather than baking it into an image or a plain manifest. The Fineract process reads the value from an environment variable or mounted file, so the secret never appears in the container image or the Git repository that holds the deployment manifests. The operator must run and patch the secrets store, the cluster's secret sync component and the Kubernetes control plane, and must decide how the store itself is unsealed after a restart. Because a secrets store that is down can block Fineract startup, the store's high availability design matters as much as the Fineract design.
- Injection path: Confirm whether the master password arrives through a Kubernetes Secret populated by a sync operator, a sidecar, or a CSI driver, and who can read that Secret.
- Store placement: Decide whether the store runs inside the cluster or in a separate trust zone, and whether a cluster compromise would also expose the store's unseal material.
- Unseal method: Confirm how the store unseals after a pod restart, whether by an external key service, manual key shares, or auto-unseal, and who holds those keys.
- Patching scope: Assign owners for the store, the sync component and the cluster, and agree on a window for rolling restarts that does not stop the write instance.
- Access review: Confirm which service accounts can read the Secret object and whether audit logs of secret reads are retained.
Before go-live, ask the platform team and the secrets store vendor which unseal and high availability mode is supported for your version and license tier.
On virtual machines or bare metal in a data center, the master password is typically delivered by an agent, a systemd unit, or a configuration management run that reads it from the secrets store and writes it to a root-owned file that only the Fineract service account can read. The file must not be placed in the application package, the shared configuration repository, or a backup that lacks encryption. Each host becomes part of the operator's responsibility, so patching, file permissions and restart behavior all fall to the infrastructure team. The secrets store usually runs on dedicated nodes with its own storage backend, and its unseal process is run by people, which makes key custody a process question as much as a technical one.
- Delivery mechanism: Confirm whether the password is injected by an agent, a templating tool, or an environment file loaded by systemd, and who can read that file.
- Host hardening: Assign owners for OS patching, SSH access and the Fineract service account, since each host holds a copy of the credential in memory.
- Store operations: Decide where the store's storage backend runs, how nodes are clustered, and who is trained to perform unseal after a planned or unplanned restart.
- Key ceremony: Document who holds unseal key shares, how they are split and stored, and how a share holder is replaced.
- Rotation runbook: Confirm that the rotation procedure can be repeated on every host without downtime for the write instance.
Before go-live, ask the infrastructure and security teams to walk through a host rebuild and a store restart in a non-production environment.
On air-gapped networks, no external secrets service is reachable, so the secrets store, its unseal material and its audit logs must all live inside the isolated boundary. The main risk is that the store becomes a single point of failure with no outside party able to recover it. Operators must plan for offline key custody, controlled media for any bootstrap material, and a documented path for software updates that crosses the boundary through an approved transfer process. Vendor support, if any, may depend on a license that is applied to the cluster and on an update path that does not require internet access. Each of these points should be confirmed before the design is frozen.
- Offline unseal: Decide how unseal keys or recovery material are split, stored in separate physical locations, and retrieved during an incident without internet access.
- Update path: Confirm how new store and Fineract images are verified and imported across the boundary, and who signs off each transfer.
- Licensing: Confirm whether any enterprise features the design needs must be licensed to a cluster that cannot reach a license server.
- Recovery drills: Schedule restores of the store and the Fineract database from offline media so the procedure is tested before an incident.
- Audit retention: Confirm where secret access logs are kept inside the boundary and how they are exported for review.
Before go-live, ask the vendor and the internal security team to confirm each offline dependency in writing, since missing one can block restart.
Keeping the master password out of images and source control
The tenant master password unlocks every tenant connection string, so one leaked copy exposes every tenant database. The controls below cover the three places secrets most often escape: build artifacts, version control and cluster configuration, plus the audit trail that shows who read them. Each control has a check you can run before go-live and repeat after every build.
Exclude secret files from build context
Docker copies everything in the build context unless told otherwise, so a local .env file, a copied application.properties or a key file can end up in an image layer. Add those paths to .dockerignore and build the Fineract image from a clean checkout. The check is to inspect the image filesystem with docker run --rm --entrypoint sh <image> -c 'ls -la /' and confirm no environment or key files are present, then review the build stage for COPY . . commands that pull in local secrets.
Scan images and layers before push
Credential strings can persist in intermediate layers even after a later step deletes them, so a clean final file list is not enough. Run a secret scanner against the built image, including its layer history, and fail the pipeline on any match for the master password or tenant connection strings. Record the scanner version and the scan result as build evidence. Ask your scanner vendor which image formats and layer types it inspects.
Block secrets in Git
Install a pre-commit hook that scans staged files for high-entropy strings and known password patterns, and repeat the scan on the Git server with a push rule so a developer who skips local hooks is still stopped. Keep the master password out of .properties, Helm values and Compose files entirely, and store only references to it. The check is a deliberately committed test string that the hook must reject.
Avoid secrets in container environment fields
Values set directly in a Kubernetes pod spec or Compose environment block are readable by anyone who can read pod specs, and they often appear in deployment history and dashboards. Mount the master password from a secret store path at runtime instead, so the value is not written into the workload definition. The check is to run kubectl get pod -o yaml and kubectl describe as a broad-role account and confirm the password does not appear.
Restrict and audit secret reads
OpenBao and Vault encrypt stored secrets before they are written to the storage backend, but encryption at rest does not limit who can ask for a secret. Bind a narrow policy to the Fineract workload's identity, such as AppRole for servers or Kubernetes auth, and deny list or read access to everyone else. Enable the audit device so that each read is logged, then confirm that a test read by an unauthorized identity is denied and appears in the audit log.
Review Git history after a leak
If a master password was ever committed, deleting the file in a new commit leaves it in history, forks and cached clones. Treat the value as compromised, rotate the master password as described in the rotation procedure, and then rewrite history with a tool such as git filter-repo only after notifying everyone with access. Confirm rotation by checking that the old value no longer authenticates to the tenants database.
Limits to confirm in your environment before committing to this design
Start by confirming that your Fineract release supports the encryption and master password mechanism exactly as its documentation describes it for that version. The project publishes documentation per release, and the current stable line is 1.15.0 with quarterly releases, so check configuration keys and property names against the tag you deploy. Do not rely on the latest documentation page alone. Then confirm how the tenants database is backed up and encrypted. Encrypted tenant and read-only schema passwords protect little if a database dump, a replica or a backup volume exposes the same connection details in readable form. Confirm backup encryption, who holds the keys, how often restores are tested and whether backup access is limited to the people who can already read the master password.
Next, confirm which OpenBao or Vault features your design depends on and whether they apply to the version you run. For storage, OpenBao documents integrated storage (Raft), PostgreSQL, PebbleDB and in-memory backends, and lists integrated storage and PostgreSQL as its supported high availability backends. HashiCorp recommends integrated storage for most use cases and gives external backends such as PostgreSQL limited support, so a PostgreSQL-backed design needs that support position confirmed in writing. Read scaling is also version dependent: OpenBao added read-only operations on Raft standbys in 2.5.0 and extended them to PostgreSQL in 2.7.0. Also note that the OpenBao migration guide was tested only against Vault 1.14.1 community edition, so any migration from a newer or licensed Vault needs its own test run.
Finally, Enterprise-only Vault features need a license applied to the cluster before you rely on them. The Vault Enterprise documentation lists performance and disaster recovery replication, HSM support through a PKCS#11 provider, namespaces, seal wrapping, FIPS compliance, Sentinel policy as code and redundancy zones among them. If your design depends on any of these, record each one as a dependency with a named owner for the license. This page does not set license terms, prices or support commitments. Those come from the vendor in writing, and HashiCorp's Vault pricing page directs self-managed Enterprise buyers to sales for a quote.
Questions teams ask before encrypting Fineract tenant passwords
What does encrypting Fineract tenant passwords cost, and what drives it?
Cost depends on the secrets store you run, how many tenants and instance types need credentials, and how much rotation testing and audit evidence your controls require. Fineract is licensed under Apache-2.0, so the spend is design, configuration, testing and any licence for the secrets platform. Setup effort is mostly one-time, while operating the store, rotating credentials and keeping audit logs recur. Ask for a quote that lists each tenant and instance type, the store chosen, the rotation test plan and the audit output expected. Any figure follows from the written scope.
How long does tenant password encryption take, and what sets the duration?
Duration depends on how many tenants and read, write and batch instances need updated connection settings, whether a secrets store already exists, and how many rotation rehearsals your change calendar allows. A single tenant with an existing store moves faster than a multi-tenant estate across several environments. Testing against a staging copy usually sets the critical path. DeployOpen does not publish durations for this topic. The written scope states the timeline and its dependencies, including access approvals and change windows.
What does our team need to provide for this work?
Plan for four groups of people before work starts:
- Platform owners who decide how Fineract instances are deployed and restarted
- Database administrators who create tenant and read-only schema accounts and can change their passwords
- A secrets store operator who runs the chosen store, its unseal process and its access policies
- Access to a staging copy of the tenants database and to the deployment pipeline
Confirm these people and their availability in the scope. Gaps in any group usually push testing or the change window back.
Can an internal team encrypt Fineract tenant passwords on its own?
Yes, a skilled internal team can do this alone if it already operates a secrets store and understands how Fineract reads tenant configuration. The gaps usually appear in rotation testing and in the audit evidence the store and deployment produce. Ask whether the team has rehearsed a master password change against a copy, and whether one named person owns the store's recovery material. A partner adds the most value where those skills or that capacity are missing. DeployOpen plans, implements, hardens and documents self-hosted platforms in your infrastructure under a fixed written scope.
Should we choose OpenBao or Vault for Fineract secrets?
Neither product is automatically the better fit. The choice depends on your licence position, support needs and what your existing estate already runs. OpenBao is licensed under MPL-2.0 and managed by the community under the Linux Foundation's OpenSSF. Its migration guide was tested only against Vault 1.14.1 community edition, so confirm any Enterprise behaviour before you choose it. Vault Enterprise features such as namespaces, FIPS compliance and HSM support need a licence applied to the cluster. HashiCorp does not publish Enterprise prices, so that cost requires a sales conversation.
What does Vault's Business Source License mean for our deployment?
Vault's Business Source License 1.1 applies to newer releases and bars competitive hosted or embedded offerings. That matters if you plan to offer a service built on the secrets store to third parties. Each version converts to MPL-2.0 four years after publication, and the Vault LICENSE file names IBM as licensor. This page does not provide legal advice. Have counsel read the terms against your intended use before you standardize on a version.
How does tenant password encryption fit with wider key management?
Tenant password encryption is one control within the wider encryption and key management work. TLS on every hop, database and backup encryption at rest, and document storage encryption need the same key owners and rotation calendar. Agree who owns the secrets store, its recovery material and its audit logs before design starts. That keeps tenant credentials, backup keys and certificate keys under one governance model. The encryption and key management topic sets the wider model, and this work plugs into it.
What goes wrong when rotating the Fineract tenant master password?
The common failures are an instance that keeps the old credential, a read replica that lags behind the change, and a restart order that breaks connections mid-process. Rotate in a staging copy first, then in production during a planned window. Confirm which write, read and batch instances read tenant credentials, and restart them in the order your design sets. Liquibase migrations run only on write instances, so keep schema changes separate from credential changes. Verify each tenant connects after the change, confirm the audit trail records who rotated and when, and keep the previous secret only for an agreed rollback window.
How DeployOpen scopes and delivers tenant secret protection for Fineract
DeployOpen plans and implements tenant connection secret protection for Apache Fineract inside your own infrastructure. We agree the scope in writing first, then build the master password, encrypted tenant and read-only credentials, rotation and secret delivery so they can be tested, documented and run by your team.
How we scope
- Inventory every tenant, its database account and each read-only schema account Fineract uses today.
- Confirm where the tenant master password is held now and which systems and people can read it.
- Agree in writing which secret store, key handling and rotation process the engagement will implement.
How we build
- Configure the tenant master password and encrypted tenant and read-only schema passwords for your environment.
- Keep the master password and database credentials out of container images, Helm values and source control.
- Test a master password rotation and a failed-startup path in a non-production environment before go-live.
How we hand over
- Deliver a runbook covering the rotation procedure, owners, recovery steps and the secret delivery design.
- Document the configuration keys, profiles and environment variables used, so your engineers can audit them.
- Walk your platform and security teams through the verification checks and the evidence each one produces.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer if you want help after handover.
- Review secret handling again when Fineract, the database platform or your secret store is upgraded.
- Confirm with your secret store vendor the license terms and supported features that apply to your edition.
