Why Apache Fineract HTTPS and reverse proxy setup needs a deliberate design
TLS termination means the encrypted connection from a client ends at a component in front of Fineract, such as NGINX or a cloud load balancer, which then forwards the request to the Fineract process. Banks need this design when a core banking API must be served over HTTPS inside their own network, when certificates must come from an internal certificate authority, or when security policy requires that traffic be inspected, logged and routed through controlled points. Fineract itself can serve HTTPS, so the first decision is whether the application should terminate TLS at all or hand that job to a proxy or load balancer.
The Fineract documentation strongly encourages HTTPS only and describes SSL settings as environment variables, including FINERACT_SERVER_SSL_ENABLED. Those settings are the starting point, not the design. Each option changes where certificates are stored, how they are renewed, which port clients reach, and what the application sees as the originating scheme and address. Teams should confirm the exact variable names and their behavior for the release they plan to run against the Apache Fineract platform documentation before writing any configuration.
The project README warns that a production deployment can be complex, costly and time-consuming, and that the project does not provide a comprehensive production deployment guide. Edge design is one of the areas where that gap shows up. Before build starts, the team should record who owns certificate issuance and renewal, which hop is encrypted and which is plain, how forwarded headers are trusted, and how the design will be tested and documented for the security and compliance reviewers who will ask.
Embedded SSL, reverse proxy or cloud load balancer: which TLS option fits
This table compares three places to terminate TLS for Fineract: its embedded SSL with a keystore, a self-managed NGINX reverse proxy in front of port 8080, and a cloud load balancer with managed certificates. Read each row across the options to see who renews certificates, where encryption stops, and which settings your team must own in Fineract.
| Question | Embedded SSL in Fineract | Self-managed NGINX on port 8080 | Cloud load balancer with managed certificates |
|---|---|---|---|
| Who renews the certificate | Your team, by replacing the keystore file and restarting or reloading the service | Your team, through the proxy's certificate files or an ACME client you operate | The cloud provider's certificate service, if the certificate is issued there; confirm renewal behavior for your provider |
| Where the TLS trust boundary sits | Inside the Fineract process, so traffic is encrypted end to end to the application | At the proxy, with traffic to Fineract on port 8080 depending on the internal network and any upstream TLS you add | At the load balancer, with traffic to the backend either re-encrypted or sent in plain text depending on configuration |
| What you configure in Fineract | SSL enabled and keystore settings through environment variables such as FINERACT_SERVER_SSL_ENABLED; confirm exact keys for your release | Embedded SSL typically disabled and the server listening on 8080; forwarded header handling must be set so URLs and redirects are correct | Forwarded header handling and the listening port; confirm the exact settings for your release and load balancer type |
| Keystore format and certificate sourcing | Confirm the keystore type and certificate source against the documentation for the release you run | Certificates are handled by the proxy, so Fineract needs no keystore unless you add upstream TLS | Certificates live in the cloud account; keystore settings apply only if you re-encrypt to the backend |
| Certificate on the initial install | The built-in self-signed certificate is for development only and must be replaced before any real use | Replace any development certificate on the proxy before exposure | Attach a certificate issued for your domain before routing live traffic |
| Operational burden | Keystore handling, restarts on renewal and tighter control over cipher settings | Proxy configuration, patching and renewal automation, plus health checks against the backend | Lowest host-level burden, with dependence on the provider's listener, certificate and logging settings |
| Auditability and evidence | Keystore and config inventory, plus renewal records you keep yourself | Proxy configuration in version control, access logs and certificate inventory | Provider logs and configuration history, which you must export and retain in your own records |
How to configure TLS termination and forwarded headers in order
This sequence moves Fineract from its built-in self-signed certificate to a proxy or load balancer that terminates TLS, forwards the original request details, and leaves the application port reachable only from the proxy. Each step ends with a check you can repeat after every change.
Confirm the release and SSL environment variables
The platform team checks which Fineract release is in use and reads the SSL settings for that release in the platform documentation, including the FINERACT_SERVER_SSL_ENABLED variable and any related keystore settings. Record the exact image tag and variable names in the change ticket so the rest of the sequence refers to the same version. Done means you have a written list of the settings you will set and the release they apply to. Confirm the variable names against the documentation for your tag, because settings can differ between releases.
Decide where TLS ends
The security architect chooses whether TLS terminates at an NGINX instance, a cloud load balancer, or an ingress controller, and whether traffic between that point and Fineract is re-encrypted. Write down who owns the certificate, which network segment carries the plaintext hop if there is one, and whether internal traffic must stay encrypted under your policy. Done means the architecture diagram shows each hop, its protocol, and the owner of each certificate. Confirm with your security team whether an unencrypted internal hop is acceptable before you proceed.
Issue and install the certificate chain
The platform or PKI team issues a certificate for the public host name, including the intermediate certificates, and installs the full chain on the proxy or load balancer rather than on the application. Keep the private key in the proxy's secret store and restrict who can read it. Done means a client that trusts your root CA completes a handshake, and the chain served by the proxy validates when you run a command such as openssl s_client against the host name. If the chain is incomplete, some clients will fail even though the browser works, so test with a clean trust store.
Set embedded SSL on or off
The platform engineer sets FINERACT_SERVER_SSL_ENABLED to false when the proxy terminates TLS and the application listens on plain HTTP on its internal port, which is typically 8080 in the default configuration. If you keep embedded SSL on for re-encryption, load a certificate that the proxy is configured to trust and document the keystore location and password source. Done means the application starts, the health endpoint answers on the internal address, and the service logs show the expected listening port. Do not leave the self-signed default certificate in any path that clients can reach.
Configure forwarded headers at the proxy
The network engineer configures the proxy to pass the original Host header, the scheme (X-Forwarded-Proto), and the client address (X-Forwarded-For and X-Real-IP where appropriate) to Fineract, and sets the proxy to trust only the upstream addresses it controls. Confirm with the Fineract documentation which forwarded-header settings the release reads so the application generates correct redirect and link URLs. Done means a request sent through the public host name shows the expected host and scheme in an echo or log entry at the application, and client addresses in logs are the real caller rather than the proxy.
Restrict direct access to the application port
The infrastructure engineer closes the application port at the host firewall, security group, or network policy so that only the proxy or load balancer subnet can reach it, and removes any public mapping of the container or service. Keep the management and actuator endpoints on a private interface if your release exposes them there. Done means a connection attempt from outside the proxy tier fails, and a connection from the proxy succeeds. Repeat this test from a host in each network segment that should not have access.
Verify redirects, chain, and tenant header end to end
The QA engineer runs a test plan through the public address: confirm that plain HTTP redirects to HTTPS, that the certificate chain validates from a clean client, and that an authenticated API call with the Fineract-Platform-TenantId header reaches the correct tenant and returns the expected data. Check that the request is logged with the forwarded client address and scheme. Done means every check passes in a non-production environment and the results are saved with the change record. Repeat the same tests after each certificate renewal and each Fineract upgrade.
How forwarded headers and the trust boundary change what Fineract sees
Once TLS ends at NGINX or a cloud load balancer, Fineract sees the connection as plain HTTP coming from the proxy, not the scheme, host and client address that the caller used. Unless the proxy forwards those values and the application is configured to read them, redirects, generated links and any logic that depends on the request scheme will reflect the internal hop instead. Confirm the exact forwarded-header behavior of the Spring Boot version in the release you deploy against the Fineract platform documentation before you write proxy rules, rather than assuming a standard header set will be honored.
Forwarded headers are client-supplied unless your edge overwrites them, so any header a caller can send is a header an attacker can forge. If Fineract trusts forwarded scheme or address values from any source, a request that arrives directly can claim to be HTTPS or come from a permitted network. The control is structural: the proxy must strip or overwrite inbound forwarding headers before it sets its own, and the Fineract port must accept connections only from the proxy. Verify this with a test that calls the application port directly from outside the proxy subnet and confirms the connection is refused, not merely that the proxy path works.
The Fineract-Platform-TenantId header selects the tenant for every API request, so the proxy must pass it through unchanged. Check that no rewrite rule, header normalization, caching rule or WAF transformation alters its case, value or presence, and that requests without it are handled as your tenant design expects. A misrouted or dropped tenant header does not fail safely in every setup, so include a multi-tenant test in your proxy acceptance checks, using at least two tenants with distinct data, and confirm each response comes from the expected tenant database.
Keystore and certificate options to decide before go-live
Most TLS problems in a Fineract deployment trace back to a few choices made early: who issues the certificate, where the keystore lives, and who renews it. Settle these before go-live so the proxy, the application and the client trust chain agree on one design.
Certificate source and trust
Decide whether the certificate comes from an internal certificate authority, a public CA, or a cloud-managed certificate service attached to a load balancer. Internal CAs suit private APIs that only your staff and systems call, but every client must trust the root. Public CAs remove that step for external callers. Confirm which option your cloud load balancer or proxy can terminate with, and where the private key will be held.
Keystore format and storage
Fineract's embedded SSL is configured through environment variables such as FINERACT_SERVER_SSL_ENABLED, so the keystore location, type and password are part of the runtime configuration. Confirm which keystore formats the documentation for your release supports before you convert certificates. Decide whether the keystore is mounted from a volume, baked into a custom image (which is a poor fit for private keys), or pulled from a secrets store at startup.
Secret handling for keystore passwords
Keystore passwords and private keys should never appear in compose files, Helm values or source control. Store them in your secrets manager or Kubernetes secrets with restricted read access, and make sure the application and proxy pods can read only what they need. Check how the password reaches the process (environment variable, mounted file or startup fetch) and whether it appears in logs or deployment history.
Rotation and renewal ownership
Name one team responsible for issuing, renewing and replacing certificates on the proxy and on the application. Automated renewal through a load balancer or cert-manager removes manual steps, but a keystore that Fineract loads at startup needs a planned restart or rollout to pick up a new certificate. Agree the expiry alert window, the rollout method and who approves emergency replacement before the first certificate expires.
Certificate chain completeness
A certificate installed without its intermediate certificates often works in one browser and fails in a service client, script or mobile app. Build the full chain in the order the server expects, install it on the proxy or load balancer, and test from outside your network using a tool that does not cache trust stores. Confirm the chain again after every renewal, since a new leaf certificate may come from a different intermediate.
Mutual TLS between proxy and application
Decide whether the proxy should present a client certificate to Fineract and verify the application's identity. Mutual TLS adds protection when traffic crosses a shared network, but it adds a second certificate lifecycle and more failure modes. If you adopt it, confirm that your Fineract release supports client certificate settings and plan how those certificates are issued, rotated and revoked. Where the proxy and application run in one private network with restricted access, document the reason if you choose not to use it.
Questions teams ask before setting up Fineract TLS
Should we use Fineract's embedded SSL or put a reverse proxy in front of it?
For most production deployments, terminate TLS at a reverse proxy or cloud load balancer and run Fineract on plain HTTP behind it, typically on port 8080. The Fineract documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED, so embedded SSL is a valid option. The deciding factors are where certificates are managed, how your network is segmented, and whether you need a proxy for other duties such as rate limiting, a web application firewall, or header control. Whichever path you choose, confirm it against your own security standards before build starts.
What does our internal team need to provide for this work?
Your team needs to supply the DNS names, the certificate authority or internal PKI process, access to the network path between the proxy and Fineract, and an owner for certificate lifecycle. Someone must also decide who approves changes to the trust chain and who can see private keys. On the application side, a platform engineer should be able to read the environment configuration and confirm how the Fineract instances are deployed. Ask a partner to state in writing which of these items they expect you to supply and which they will handle.
How long does TLS setup take, and what changes the timeline?
Duration depends mainly on the environment and on approvals, so no fixed figure applies across deployments. The main drivers are how many environments need certificates (development, test, staging and production), whether certificates come from a public authority or an internal PKI, how many network teams must sign off on firewall and DNS changes, and whether the work is done inside a change window. Ask for a timeline built from your environment inventory and your approval workflow, and confirm the approval lead times with your network and security teams first.
Does a cloud load balancer remove the need for a reverse proxy?
A cloud load balancer can terminate TLS, so in many designs it replaces a separate NGINX tier, but it does not remove the need to configure forwarded headers. Fineract must know the original scheme and client address, so the load balancer and the application need matching settings for X-Forwarded-Proto and X-Forwarded-For. Check which features you rely on, such as path routing, header rewriting, or access logging, and confirm that the load balancer supports them. If you need custom request handling, a proxy may still be the better fit.
How is certificate renewal handled, and who gets alerted?
Renewal should be automated or scheduled as an owned process, with monitoring that warns before expiry. Decide whether renewal runs through your certificate authority tooling, a Kubernetes certificate manager, or a manual change process, and document who receives expiry alerts. Test the renewal path in a non-production environment, including the reload of the proxy and any keystore files. Expired certificates are a common cause of outages, so the renewal runbook should be treated as an operational control, not a one-time setup task.
What does a keystore option change in the build?
A keystore matters when Fineract itself terminates TLS, because the certificate and private key must be loaded into the Java runtime from a file or secret. The choice affects how keys are protected, how they are rotated, and how the container image is built. Store the keystore password in a secrets manager rather than in a configuration file, and confirm how your deployment platform mounts those files. Keep the keystore format and the password handling documented so that renewals do not depend on one person.
What evidence will an auditor expect for TLS on a core banking system?
Auditors usually want to see the approved configuration, the certificate inventory, evidence of who can change keys, and logs showing that unencrypted access is refused. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue any audit report or attestation. Ask your assessor which evidence formats they accept before the work begins, so the configuration, change records and test results are captured in the right form from the start.
What drives a partner quote for this work?
A quote follows from the written scope, and DeployOpen does not publish a price list. The main cost components are the number of environments, the network design (public, private or VPN-only access), the number of Fineract instances and the proxy layers involved, the size of the certificate estate, and the amount of audit evidence required. One-time costs cover design, build and testing. Recurring costs cover renewal support and any retainer for ongoing operations. Ask for the quote to list each deliverable, the responsibilities split, and the assumptions about your environment.
Limits and items to confirm in your environment
The items below are the points where a Fineract TLS design most often fails when it meets a real environment. Each one is a question to settle with the Fineract release you run, the load balancer vendor, the front-end team and your certificate authority before the configuration is finalized. Treat each answer as a written decision that goes into the design record.
Release and environment variables
Confirm which Fineract release you will run and check the SSL and server settings against the documentation for that exact version. The documentation names variables such as FINERACT_SERVER_SSL_ENABLED, and names and defaults can differ between releases. Record the release tag, the variables you set and the values they take, so a later upgrade does not silently change how TLS is terminated. The version you test must match the version you deploy.
Load balancer protocol and header support
Check whether your cloud load balancer or ingress can forward the protocol Fineract expects, pass through forwarded headers and preserve the original host and scheme. Ask whether it re-encrypts traffic to the backend or sends plain HTTP, and whether backend certificate validation is supported. Some managed load balancers cannot trust a custom CA for backend connections, which changes the design. Confirm this with the vendor against your exact service tier.
Front-end origins and CORS
If the Mifos web application or another browser client calls the Fineract APIs, list every origin that will reach the API and decide how CORS responses are set. A mismatch between the public hostname, the proxy hostname and the allowed origins usually shows up as blocked requests after go-live. Confirm with the front-end team which origins, methods and headers they need, and test sign-in from each one. Do not allow wildcard origins on a banking API without a documented reason.
Long-running and streaming requests
Confirm how the proxy handles long requests, such as large report exports, batch calls and any connection that stays open. Check idle timeout values at the load balancer, the proxy and the application, since a shorter timeout in one layer can cut off a transaction the back office expects to finish. Ask the Fineract and client teams whether any part of their workflow uses websocket or streaming connections, and test that path through every hop.
Internal CA and certificate policy
Confirm what your internal certificate authority requires: issuing authority, key length and algorithm, validity period, renewal process, revocation checking and where the private key may be stored. Decide whether the proxy certificate is public, internal or both, and whether the Fineract instance needs a keystore or only the proxy holds the certificate. Get the policy in writing from the security or PKI team before requesting certificates, because the answer changes the renewal runbook.
Trust chain for backend connections
If traffic between the proxy and Fineract is encrypted, confirm which trust store the proxy and the application use, and who maintains it. Ask whether the internal root and intermediate certificates are distributed to every instance, including read and batch instances, and how a rotation is rolled out without an outage. Test the chain from a clean container image, since a trust store that works on a developer machine often fails in production.
Operating certificates, upgrades and monitoring after go-live
The recurring cost of a Fineract TLS setup sits in four places: renewing certificates before they expire, retesting the proxy after each Fineract upgrade, watching expiry dates on every certificate in the path, and keeping a current record of where trust is terminated. Build a renewal calendar that lists each certificate (public endpoint, internal re-encryption certificate, keystore if one is used) with its owner, issuer, expiry date and the deployment that consumes it. Automate issuance and renewal where your certificate authority supports it, and confirm that renewal does not require a restart of NGINX, the cloud load balancer or the Fineract instances unless your runbook accounts for that restart.
Fineract's release cadence drives the second task. The project's README states that official releases are created quarterly, at the end of each quarter, and that end-of-life releases are archived. Before changing an image tag, read the release notes and the Apache Fineract platform documentation for changes to the FINERACT_SERVER_SSL_* settings, forwarded header handling, actuator endpoints and health checks, since any of these can break a working proxy. Run the proxy test suite against a staging copy with the new tag, including login through the front end, a token request, a write request and a batch request, and confirm that X-Forwarded-Proto still produces the scheme your application expects. Monitor expiry with an external probe that checks the served certificate, not only the files on disk.
Your audit evidence should show the trust boundary clearly: where TLS ends, which hops are re-encrypted, which certificate authority issued each one, and who may change the proxy configuration. Keep this as a versioned document next to the NGINX or load balancer configuration, and update it in the same change that alters the boundary. Confirm with your auditor which artifacts they expect (configuration exports, renewal logs, probe history) and retain them for the period they require. DeployOpen can prepare these records as part of a readiness engagement, but independent auditors and certification bodies make the assessment.
Official Apache Fineract sources for this topic
Where is the official Apache Fineract documentation for HTTPS setup?
The official Apache Fineract platform documentation is the starting point for HTTPS and SSL settings. The project strongly encourages HTTPS only and documents SSL options through environment variables, including FINERACT_SERVER_SSL_ENABLED. Read the configuration reference alongside the variable list before you change any default. Documentation reflects the current release line, so confirm each setting against the tag you deploy. Record which settings you changed, which you left at default, and why. That record helps an auditor, an upgrade engineer or a new administrator follow the decision later. The documentation defines setting names and behavior. Your own certificate policy and proxy design decide how traffic reaches Fineract.
Does the Fineract source code show how the embedded server handles SSL?
Yes. The apache/fineract repository on GitHub holds the configuration files, default values and Spring profile files that control the embedded server. When documentation and behavior seem to differ, the source in the tag you deploy is the authoritative check. Engineers should read the files for the exact release, not the main branch, because defaults can change between versions. Compare the server and SSL settings in that tag with your intended proxy design before you disable embedded SSL. Keep a copy of the reviewed files with your change record. This step is especially useful when you plan a move from the built-in self-signed certificate to a certificate issued by your own authority or a cloud load balancer.
Does the Fineract README give production guidance for TLS termination?
The README explains the project basics, including quarterly releases, PostgreSQL as the recommended database, and authentication options. It also warns that the project does not provide a comprehensive production deployment guide. TLS termination, forwarded headers, certificate lifecycle and proxy hardening are therefore decisions your team must design and document. The README also notes that a production deployment can be complex, costly and time-consuming, and that organizations may pay a vendor for deployment and maintenance. Use the README to understand project scope, then write your own TLS standard covering certificate issuance, renewal, cipher policy, header handling and monitoring. Ask any implementation partner to deliver that standard in writing as part of the agreed scope.
Which Fineract release should I check before changing SSL settings?
Check the release you actually run. The Apache Fineract website lists 1.15.0 as the current stable release, and the 1.15.0 documentation was built on July 10, 2026. The README states that official releases are created quarterly, at the end of each quarter, following the ASF release policy, and that end-of-life releases are archived. Because settings can change between releases, pin your SSL configuration to the version in your deployment record. Before an upgrade, confirm that the new release still supports your proxy design and certificate method. Ask your team to verify this on a staging environment that uses the same image tag as production.
Why does TLS matter for Fineract authentication settings?
The Fineract README shows OAuth2 and HTTP basic authentication, and it uses a default development login that must be changed for any real deployment. With basic authentication, credentials are sent with requests, so the connection between clients and the platform must be encrypted end to end or terminated at a point you control. The documentation strongly encourages HTTPS only, which makes TLS a baseline control rather than an optional hardening step. Confirm where encryption ends in your design, whether at the load balancer, at NGINX or inside the application, and whether traffic between the proxy and Fineract also uses TLS. Document that path for your security review and test it with a packet or header inspection before go-live.
Can DeployOpen set up the reverse proxy and certificates for Fineract?
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, which includes cloud accounts, data centers and air-gapped networks. Proxy, TLS and certificate work can be part of a fixed-scope engagement, with the scope, deliverables and timeline agreed in writing before work starts. The written scope should name the proxy product, certificate source, renewal process, header rules and test evidence. Ask for these items in any quote. DeployOpen does not publish prices, so a quote follows from the written scope. Your team keeps ownership of the certificate authority, key custody and change approval, and should confirm those responsibilities in the statement of work.
Where should I report a Fineract TLS problem I cannot resolve?
Start with the apache/fineract repository on GitHub, which is the project's public code home. Search existing issues for your release and error message before you open a new one. Include the image tag, the proxy product and version, the relevant configuration keys with secrets removed, and the exact handshake or header error. Confirm the problem on a clean staging deployment so you can separate a Fineract setting from a proxy rule. The project does not offer a production support contract through this page, so a vendor or partner may be needed for urgent production work. Plan that support route before go-live, not during an outage.
How DeployOpen scopes TLS and proxy work in a fixed-scope engagement
DeployOpen agrees the scope, deliverables and timelines for TLS and reverse proxy work in writing before any configuration starts. For this topic, the written scope usually names the proxy or load balancer in use, the hostnames and certificate sources, whether Fineract's embedded SSL is replaced or switched off, the forwarded header behavior the proxy must provide, and the environments covered, such as development, test and production. A quote follows from that written scope. DeployOpen does not publish a price list, so the reader should ask for a quote that lists each of these items separately.
The work is carried out inside the client's own infrastructure, in their cloud accounts, data centers or private networks. Typical deliverables are the proxy configuration, the Fineract settings that match it (for example, the FINERACT_SERVER_SSL_ENABLED variable and the port Fineract listens on), a runbook for certificate renewal, and verification records showing that HTTPS terminates at the expected point and that the application receives the correct client address and scheme. DeployOpen prepares this configuration and evidence for the client's own review. It does not issue audit reports, attestations or certifications, so any compliance mapping that depends on TLS settings must be confirmed with the client's independent assessor.
Before signing, ask the proposal to state who owns certificate issuance and renewal after handover, which party holds access to the proxy and its private keys, and what happens if the scope changes during the build, such as adding a second tenant hostname or moving from a self-managed proxy to a cloud load balancer. Ongoing changes to TLS settings, certificate rotation and proxy upgrades are normally handled under a separate retainer, so the reader should confirm which of these activities sit inside the fixed scope and which are recurring.
How DeployOpen delivers Fineract HTTPS and reverse proxy setup
DeployOpen plans and implements Apache Fineract HTTPS and reverse proxy setup inside your own infrastructure, whether that is NGINX, a cloud load balancer or an ingress controller. We agree the TLS, header and network design in writing before work starts, then build, test and document it so your team can run it.
How we scope
- We confirm which edge components you run, such as NGINX or a cloud load balancer, and where TLS ends.
- We agree whether Fineract's embedded SSL stays off and traffic reaches port 8080 behind the proxy.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work begins.
How we build
- We replace the built-in self-signed certificate with certificates issued by your own certificate authority.
- We configure forwarded headers so Fineract sees the correct scheme, host and client address behind the proxy.
- We test HTTPS redirects, tenant header routing and REST access paths against the Fineract 1.x deployment you run.
How we hand over
- We document the proxy configuration, certificate sources, keystore choices and renewal steps in a handover pack.
- We record the reasons for each design decision so auditors and future engineers can trace the TLS setup.
- We walk your operations team through certificate rotation and troubleshooting before the engagement closes.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- We can review the TLS and proxy configuration again when you move to a newer Fineract release.
- Retainer scope, response expectations and service terms are confirmed in writing before any support starts.
