Apache Fineract with the Mifos X web app

How the Mifos X web app gives Apache Fineract a staff interface

Apache Fineract has no user interface of its own. It exposes REST APIs, so the branch and back-office staff who open accounts, approve loans and post transactions need a separate front end. The Mifos X web app fills that role. It is the Angular user interface of Mifos X, and it uses Apache Fineract as its backend. The web app is licensed under MPL-2.0, which is a different license from Fineract's Apache License 2.0, so your license review should cover both components as they will be deployed together.

The integration method is simple: a browser client calling the Fineract REST API. The web app runs in the staff member's browser, and every screen translates into API requests to your Fineract instance. The supported connection is set through two settings named in the web app README, FINERACT_API_URL and FINERACT_PLATFORM_TENANT_IDENTIFIER. The tenant identifier must match an entry in the Fineract tenants table, so a mismatch shows up as a login or data problem rather than a clean configuration error. Confirm the current variable list in the openMF/web-app repository before you write your deployment configuration.

Plan the staff interface as part of the platform, not as an afterthought. Decide which browsers and network paths staff will use, where the web app is hosted, and how its HTTPS traffic reaches Fineract, since Fineract's documentation strongly encourages HTTPS only. Ask your team to confirm how the web app's release line maps to your Fineract version before you pin either component, because the two must stay compatible through upgrades.

What you need before connecting the web app to Fineract

The web app is a thin Angular client, so most failures trace back to the Fineract instance, the tenant setup or the network paths around it. Confirm these six items before you change any web app setting. Each one is a decision you can review with your platform and security teams.

A running Fineract 1.x instance

The web app calls the Fineract REST API, so you need a working Fineract 1.x instance before the front end is configured. Fineract 1.15.0 is the current stable release according to the project website, and the web app release must match that line. Confirm the instance responds to API calls with your test credentials before you deploy the front end. Fineract is a headless application and provides no user interface of its own.

PostgreSQL as the database

The Fineract README recommends PostgreSQL, and MariaDB and MySQL are deprecated under FSIP-9. Plan the web app around a PostgreSQL-backed Fineract, because the official Docker image ships only the PostgreSQL JDBC driver. Confirm that database backups and restore tests cover the Fineract tenants database as well as the tenant data databases.

A tenant identifier that matches

The web app sends a tenant identifier that must align with an entry in the Fineract tenants table. Set FINERACT_PLATFORM_TENANT_IDENTIFIER to the exact identifier, including case, and test a call with the Fineract-Platform-TenantId header before the login screen is exposed. A mismatch usually shows up as a login or data error rather than a clear message, so record the identifier in your configuration standard.

A web app release matching the Fineract line

The reference release is v1.0.0-fineract1.14, published on December 23, 2025. Its version label names the Fineract line it targets, so a 1.14 web app is not a safe default for a 1.15.0 instance. Check the openMF/web-app releases page for the release that matches your Fineract version, and confirm it with the openMF project before you pin the image tag. Record the pairing as part of your change control.

Network paths in both directions

Two paths must work. Staff browsers must reach the web app, and the web app server must reach the Fineract API, usually through the same gateway or ingress controls you apply to other internal services. Map each path, the ports it uses and the firewall or proxy rules that govern it. Confirm that the browser never needs direct access to the Fineract API if your design keeps the API private.

TLS certificates on both hops

Fineract strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Issue certificates for the web app hostname and the Fineract API hostname from a CA your staff browsers and the web app server trust. Confirm the certificate chain, expiry monitoring and renewal owner before go-live, because an expired certificate blocks login for every user at once.

Configuring the web app against your Fineract instance

This sequence connects the Mifos X web app to a running Apache Fineract instance and confirms that staff can sign in and read live data. It ends with a tested login and a verified client search and loan product read, so the team knows the front end and the back end agree on the tenant and version.

Confirm Fineract and the tenant are reachable
The platform team checks that the Fineract API answers on the network path the web app will use, and that the target tenant exists in the tenants database. Send an authenticated read request to the clients endpoint with the Fineract-Platform-TenantId header set to the tenant identifier. Fineract is multi-tenant, so a wrong tenant identifier returns errors even when the server is healthy. Done when the request returns a JSON response for the expected tenant and a request with a different identifier does not return that tenant's data.
Match the web app release to Fineract
Before you set any variables, pick the web app release that targets your Fineract line. The openMF/web-app repository published v1.0.0-fineract1.14 on December 23, 2025, and its release tag names the Fineract version it was built against. Read the release notes and the openMF web app releases page to confirm the pairing, and record the web app tag and the Fineract version in your change log. Done when both versions are written down and the pair is confirmed against the release notes rather than assumed from the version number alone.
Set API URL and tenant variables
The engineer sets FINERACT_API_URL to the base address of the Fineract API and FINERACT_PLATFORM_TENANT_IDENTIFIER to the identifier stored in the tenants table. The web app README lists these and related variables, so work through the full list and do not carry settings over from another environment. The tenant identifier must match the tenants table exactly, including case. Done when a configuration file or environment file for each environment holds the values, and a test build loads without a configuration error in the browser console.
Choose Docker or a static build
The engineer selects one deployment path. Docker or Docker Compose suits teams that want the web app packaged with its variables and restarted as a unit. A static build suits teams that already serve static files from a web server or a Kubernetes ingress. Both paths take the same variables from step three, so the choice affects operations, not behavior. Confirm the build steps in the repository README for the release you chose. Done when the chosen path produces a running app that serves the login page from the internal address.
Serve the app over HTTPS
Place the web app behind TLS so staff sessions and credentials never travel in clear text. Terminate TLS at a reverse proxy or ingress with a certificate issued by your internal or public certificate authority, and confirm the proxy forwards requests to the app and to the Fineract API using the addresses in your configuration. Fineract also documents HTTPS settings such as FINERACT_SERVER_SSL_ENABLED, which the team should enable for its own API connection. Done when the login page loads over HTTPS with a valid certificate and the browser reports no mixed content warnings.
Replace the default login with a named account
The Fineract README shows a default development login, and it must not survive into a real deployment. Create a named staff user in Fineract with the roles that match that person's duties, then sign in to the web app with that account. Disable or change the default credentials according to your identity design, and confirm that the default login no longer works. If you plan to replace basic login with OAuth2 later, treat this account as a stepping stone and record that decision. Done when a named user signs in successfully and the default credentials are rejected.
Verify client search and loan product read
Use a named test client that exists in the tenant to check the search function in the web app. The result should match the client record shown by a direct API call with the same tenant header. Next, open the loan product list and confirm that the products match the configuration your team approved for that tenant. Illustrative example: if the approved list has three products, the web app should show the same three, with the same names and currencies. Done when the search returns the expected client and the product list matches the approved configuration, which closes the sequence.

Choosing between Docker and Docker Compose options

Running the web app as a single container means one image serves the Angular front end, and you point it at a Fineract instance that you run separately. This is the smallest footprint and suits a lab, a proof of concept, or a team that already operates its own container platform and wants the web app as one more workload. The trade-off is that everything around the container is your responsibility: the database, the reverse proxy, certificates and the network path between the browser and the API.

Upgrades: you replace one image tag and restart one container, but you must check the web app tag against the Fineract version it targets.
Environment variables: settings such as FINERACT_API_URL and FINERACT_PLATFORM_TENANT_IDENTIFIER are passed directly on the run command or in your orchestrator's config.
TLS termination: nothing in the container terminates TLS for you, so you need an external load balancer or proxy in front of it.
Dependencies: Fineract, PostgreSQL and the proxy are deployed and versioned by you, outside this unit.
Rollback: reverting means redeploying the previous tag, which is simple if the old image is retained.

Before choosing this option, confirm the current image tags and supported variables in the openMF/web-app repository.

A Compose stack defines the web app, Fineract, PostgreSQL and a reverse proxy in one file, so the whole set starts, stops and connects together. It fits a single host or a small set of servers where a team wants a repeatable, reviewable definition without operating a cluster. It also makes the internal network explicit, so the database and Fineract need not be exposed beyond the proxy. The cost is that Compose has no built-in high availability or rolling upgrade across hosts, so those duties stay with your team.

Upgrades: you change image tags in the Compose file, pull, and recreate services, and you should pin tags so an unplanned pull cannot move a version.
Environment variables: shared values can live in an .env file or an environment block, which keeps tenant identifiers and API URLs in one reviewed place.
TLS termination: the reverse proxy service can terminate HTTPS for the web app and Fineract, with certificates mounted as files or secrets.
Network isolation: only the proxy publishes ports, while PostgreSQL stays on an internal network.
Database version: the PostgreSQL service tag is set in the same file, so confirm it against the Fineract release notes and the project's PostgreSQL recommendation.

Confirm current image tags and the Fineract release that matches your web app build before you pin anything.

The Fineract README uses Kubernetes as its production example, and it separates Fineract's instance types and database migration step in ways a single host cannot easily reproduce. Fineract documentation describes write, read and batch instances, and Liquibase migrations run only on write instances, with a liquibase-only Spring profile available on Kubernetes. The web app is one more deployment in that cluster. This option suits organizations that already run Kubernetes and need scaling, health checks and controlled rollouts, but it adds cluster operation as a cost in its own right.

Upgrades: rolling updates and revision history support rollback, but database migration order must be planned with Fineract.
Environment variables: values come from ConfigMaps and Secrets, which keeps credentials out of manifests.
TLS termination: an ingress controller or gateway usually terminates TLS, with certificates managed by your certificate tooling.
Scaling: the web app and Fineract read instances can scale independently of the write instance.
Platform ownership: the cluster, ingress, storage and backups need an owner who can run them.

Treat the README's Kubernetes example as a reference design, and confirm its current manifests and profiles against the Fineract documentation.

How OAuth2 login replaces basic authentication in the web app

The Fineract README shows two ways to authenticate API calls, OAuth2 and HTTP basic authentication, and it ships with a default development login of mifos and a password that must be changed before any real use. For a staff-facing deployment, that default is the first control to remove. Basic authentication sends credentials with every request, so the web app would need the user's password on each call. OAuth2 moves the login to an identity provider and lets the web app work with a bearer token instead. Decide early which identity provider will issue staff tokens, who administers it, and how staff accounts map to Fineract users, because the web app and Fineract must agree on that identity.

In the token flow, the user signs in at the identity provider, the web app receives a token, and each Fineract request carries that token along with the Fineract-Platform-TenantId header that identifies the tenant. Fineract still authorizes each action against the Fineract user and its roles, so the identity provider handles authentication and Fineract keeps the permission model. The web app is configured through its own environment variables, including FINERACT_API_URL and FINERACT_PLATFORM_TENANT_IDENTIFIER. The public material does not list every OAuth2 setting the web app needs, such as the client identifier, redirect addresses or token endpoint configuration, so confirm each one against the web app README and the release you deploy before you write the configuration.

The realm, client and token-subject mapping for Keycloak are covered in the sibling topic on Apache Fineract and Keycloak OAuth2 integration. Use that page for the identity setup rather than duplicating it here. Test the login path end to end in a non-production environment: sign in as a staff user, confirm the token reaches Fineract, check that a user without the right role is refused, and confirm that the default mifos login no longer works. Record who owns the identity provider, since a lockout or a changed client secret will stop every branch from working at once.

Mapping tenant, server and user settings between the web app and Fineract

This table maps each web app setting to the Fineract object or request element it must match, from the API base URL and TLS endpoint to the tenant identifier and the user or token subject. Read it as a checklist: a mismatch in any one row usually shows up as a login failure or an empty data screen rather than a clear error.

Setting or element	Where it lives in Fineract	What must match	What to confirm before go-live
FINERACT_API_URL	Base URL of a Fineract read or write instance behind your ingress	Reachable from the browser or web app server, ends at the REST API root, and uses HTTPS	Confirm the exact path form in the web app README and test a request with curl from the web app network
FINERACT_PLATFORM_TENANT_IDENTIFIER	Identifier column of the tenants table in the tenants database	Identical string, including case, to the tenant row the API will resolve	Confirm the value with the database owner, not from a default in a sample file
Fineract-Platform-TenantId header	Sent by the client on every API request, read by Fineract to select tenant connections	Same value as the tenant identifier; a request without it or with another tenant resolves to different data	Trace one login and one list call in the network log to confirm the header is present on each request
TLS endpoint	HTTPS listener in front of Fineract, with certificate and SSL settings such as FINERACT_SERVER_SSL_ENABLED	Certificate names match the host in FINERACT_API_URL and the web app origin is allowed by Fineract's CORS and redirect settings	Confirm certificate chain trust in the browser and in the web app container, since a self-signed chain fails silently in some builds
Web app OAuth2 settings	Authorization server issuer and client registered for the web app	Redirect URI and issuer in the web app match the client configuration in the identity provider	Confirm the setting names in the web app README for your release, as they change between versions
Token subject and user account	Username mapped into the token subject, and the Fineract user with roles and office	Subject claim maps to an existing Fineract user in the same tenant and office, with permissions set	Test a staff user from each office and role, because a user in the wrong office sees a partial portfolio
Basic authentication fallback	Development login shipped in the README, which must be changed	No default credentials remain in any environment reachable from a network	Confirm the default is removed in every environment, including staging and the web app build

Security settings for the web app and its Fineract connection

The Mifos X web app is a browser front end that calls Fineract's REST APIs, so the web app, its hosting, and the Fineract connection share one trust boundary. The cards below cover the settings that protect that boundary, from transport encryption to the lifetime of sessions and tokens.

Enforce HTTPS only

Fineract's documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Enable SSL on the Fineract API and serve the web app over HTTPS as well, so staff credentials and bearer tokens never travel in clear text between the browser, the web app and Fineract. Check that every hop behind a load balancer or ingress is also encrypted, and confirm the certificate chain is trusted by the browsers your staff use.

Replace the default login

The Fineract README ships a development login of mifos with a default password, and it must be changed for any real deployment. Remove or rotate that account before the web app is exposed to staff, and confirm that no seeded test users remain in the tenant. Decide whether staff log in through OAuth2 with an external identity provider or through basic authentication, and document which accounts can administer the platform.

Restrict who can reach the web app

Limit network access to the web app and the Fineract API to the networks your staff and support teams use, such as a corporate network range or a VPN. Place the web app behind your gateway or reverse proxy with its own access rules, and do not expose the Fineract API directly to the internet for the convenience of the web app. Confirm which paths the web app needs and block administrative endpoints from public routes.

Protect tenant identifiers and secrets

The web app reads FINERACT_PLATFORM_TENANT_IDENTIFIER and related variables from its environment, and Fineract selects tenant connections using the Fineract-Platform-TenantId header. Keep database credentials, client secrets and tenant identifiers in a secrets store or restricted environment files, not in images or source control. Limit read access to these files, rotate credentials on a schedule your team sets, and confirm that tenant identifiers match the Fineract tenants table.

Review session and token lifetimes

Set how long a browser session stays valid after inactivity and how long access tokens remain usable. When Keycloak or another OAuth2 provider issues the tokens, the lifetimes are set there, so align them with your staff policy and confirm that logout ends the web app session as well as the provider session. Test what happens when a staff member is disabled, since an existing token may stay valid until it expires.

Secure APIs the browser can reach

Any Fineract endpoint the web app calls is reachable by anyone who can obtain a valid token, so it needs the same authentication, authorization, logging and TLS controls as the core system. Do not treat the web app as a trusted layer that filters requests for Fineract. Review which API operations staff roles can perform, check audit logs for administrative changes, and include the web app in your penetration test scope.

Keeping the web app and Fineract versions aligned through upgrades

The web app must be pinned to a release built for the Fineract line you run. Apache Fineract ships official releases quarterly, at the end of each quarter, and archives end-of-life releases, so the Fineract version in production will change on a regular cycle. The Mifos X web app is a separate project with its own release tags, and its releases are named to indicate the Fineract line they target. The reference release is v1.0.0-fineract1.14, published on December 23, 2025. Treat that tag as a reference for the 1.14 line only. It does not imply compatibility with any newer Fineract version, and you should confirm the matching web app tag for your exact Fineract release in the openMF/web-app releases page before you schedule an upgrade. Record the pairing in your change register so that anyone reading the environment can see both versions.

Upgrade in a fixed order: Fineract in a non-production tenant first, then the web app, then staff regression. Start by upgrading Fineract in a non-production environment that holds a copy of your tenant data, and confirm that the FINERACT_API_URL and FINERACT_PLATFORM_TENANT_IDENTIFIER values still match the tenants table after any database changes. Next, deploy the web app release that matches that Fineract line and point it at the upgraded test instance. Then run a regression pass through the workflows your branch staff use daily: client creation, loan application and approval, disbursement, repayment, savings transactions, and the reports your operations team relies on. Include the Close of Business run in that pass, because a Fineract upgrade can change batch behavior that staff will not see in a simple login test. Only after those checks pass should you promote both components together.

Plan a rollback point before production, because the web app cannot undo a Fineract database migration. Liquibase migrations run on write instances during a Fineract upgrade, so a rollback usually means restoring the database from a backup taken immediately before the change, not reverting code alone. Keep the previous web app build available so you can redeploy it quickly if staff find a defect after go-live. Ask your DeployOpen or internal team to define who approves the production cutover, how long the old build stays deployable, and which staff workflows must be signed off before the change window closes. Schedule the web app and Fineract changes in the same window, and avoid leaving the two components on different quarterly lines for longer than your testing cycle requires.

Common web app connection failures and how to fix them

This table lists the connection failures most often seen when the Mifos X web app sits in front of Apache Fineract, with the likely cause and the fix for each. Check the symptom column against what staff see, then work through the cause and fix before changing anything else.

Symptom	Likely cause	Fix
Login succeeds but no tenant data loads	FINERACT_PLATFORM_TENANT_IDENTIFIER does not match an entry in the Fineract tenants table	Query the tenants table in the tenants database, copy the identifier exactly (case and spelling), set it in the web app configuration, and rebuild or restart the web app
Spinner or network error on every page	FINERACT_API_URL is wrong, points to a host the browser cannot reach, or omits the path Fineract serves	Open the Fineract API URL directly in the browser from a staff workstation, confirm it returns a response, then set the variable to that exact base URL
Browser blocks requests with mixed content	The web app is served over HTTPS but FINERACT_API_URL uses HTTP	Use an HTTPS URL for the API, and confirm the reverse proxy terminates TLS for both the web app and Fineract hosts
Certificate error on API calls	The API certificate is self-signed, expired, or issued for a different hostname than the one in FINERACT_API_URL	Install a certificate that covers the API hostname and chain to a CA staff browsers trust, or distribute your internal CA to workstations
CORS errors in the browser console	The Fineract origin does not allow the web app origin, or the proxy drops or duplicates the CORS response headers	Confirm the allowed origin matches the web app scheme, host and port exactly, and let one layer (proxy or Fineract) set CORS headers, not both
Wrong host, scheme or port in redirects or links	The reverse proxy does not forward host and protocol headers, so Fineract builds URLs from internal addresses	Forward the original Host and X-Forwarded-Proto headers at the proxy and confirm the Fineract server trusts them as the proxy sets them
Login fails after switching from basic authentication to OAuth2	Stored browser sessions, the old client configuration, or a token issuer or client ID mismatch with the identity provider	Clear browser site data for the web app, confirm the client ID, redirect URI and issuer match the identity provider, and test with a new private browser session
Blank screen after upgrading the web app or Fineract	The web app build and Fineract release are out of step, so API responses no longer match what the front end expects	Pair the web app release with the matching Fineract release line, check the release notes for both, and roll back the pair together if needed
Records appear missing or stale after creating data	The web app reads through a read instance or replica that has not yet received recent writes, or the write path is not used for mutations	Point the write-path API traffic at the write instance, use read instances only for reads that tolerate replication delay, and confirm the routing with a test record

Questions buyers ask about the Mifos X web app and Fineract

Is the Mifos X web app required to use Apache Fineract?

No. Apache Fineract is headless and provides REST APIs without its own user interface, so any client that can call those APIs can serve staff. The Fineract README names the Mifos X web application as the front end used in its Kubernetes example, which makes it the common starting point rather than a requirement. Your choice depends on whether your staff need a ready-made browser interface for branches, back office and reporting, or whether you plan to build and maintain a custom front end. Confirm with your team which screens and roles they need on day one before deciding.

How long does a basic Mifos X web app connection take to set up?

No duration is published for this, and the answer depends mostly on your environment. The main drivers are whether a Fineract instance and PostgreSQL database already run in your infrastructure, how many tenants you need, whether login goes through basic authentication or an OAuth2 provider, and how your TLS certificates and hosting are managed. A single tenant on an existing, reachable Fineract instance is a much smaller task than a new platform with identity integration. Ask any partner for a timeline built from a written scope and your current environment inventory.

What cost components should we expect when adding the web app?

Expect four components. Internal staff time covers architecture decisions, environment access, testing and training. Partner fees, where used, usually cover fixed-scope configuration, deployment and handover, and DeployOpen agrees these in writing before work starts. Hosting covers the compute, storage and network for the web app and Fineract, which recur monthly or yearly. TLS covers certificates and their renewal, which also recur. Ask for a quote that separates one-time setup from recurring hosting, certificate and support costs, and that lists which environments are included.

Can our own team set up the Mifos X web app without outside help?

Yes, if your team has experience running Java and Angular web applications, PostgreSQL and container platforms, and a clear owner for tenant configuration. The Fineract 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, so plan for research and testing time. Teams often start with a non-production environment, confirm login, tenant and API connectivity, and then decide what to outsource. Confirm your skills against the web app README and the Fineract documentation before committing.

What do we need to provide before the work starts?

Prepare a few concrete inputs. You need the Fineract tenant identifiers and the tenants database details, because the web app's tenant identifier must match the Fineract tenants table. You need access to the identity provider if you plan to use OAuth2 login, including a client registration and test users. You also need test accounts with defined roles in a non-production Fineract environment, hostnames and certificates, and a named owner who can approve changes. Ask the partner to list these inputs in the written scope so gaps show up early.

How do we keep the web app and Fineract versions aligned?

Pin both components to versions that the projects document as compatible, and test every change in a non-production environment before promoting it. The web app repository lists releases such as v1.0.0-fineract1.14, which signals the Fineract line it targets, while Fineract publishes official releases quarterly and lists 1.15.0 as the current stable release. Confirm compatibility in the web app release notes before any Fineract upgrade, and record the pairing in your change log. Also watch Fineract's end-of-life notices so your pairing does not fall out of support.

Does the web app need its own login, or can it use our identity provider?

The web app can sign staff in through the authentication Fineract exposes, and Fineract documents OAuth2 alongside HTTP basic authentication. Basic authentication uses a default development login that must be changed before any real use, so do not expose it in production. Connecting an external OAuth2 provider is a separate integration with its own realm or client setup, token mapping and testing. Confirm the exact login flow your web app version supports with the vendor documentation before you commit to a design.

How DeployOpen scopes and delivers the web app connection

DeployOpen plans and implements a self-hosted Apache Fineract backend and its Mifos X web app front end inside your own infrastructure, whether that is your cloud accounts, data centers or an air-gapped network. Fineract is headless and ships no user interface of its own, so the web app is a separate component with its own release, configuration and hosting decisions. The scope we write down should name each of them: the Fineract instance and its tenants, the web app build, the reverse proxy and TLS termination in front of both, the identity provider used for staff sign-in, and the environments in which each component runs. A written scope fixes these boundaries before any configuration starts, so that each side knows who owns which setting when something breaks.

Engagements run from a written fixed scope with agreed deliverables and timelines. Before work starts, we confirm the target Fineract release and the matching web app release, because the two must be kept aligned, and we record the values for the web app's API URL and tenant identifier against the tenants table in your Fineract database. Deliverables typically include the deployment configuration, the login path, a runbook for upgrades, and test evidence showing that staff can sign in, act within their tenant and reach the expected screens. Your team should confirm which hostnames, certificates and network routes they can provide, since those usually determine the timeline more than the web app configuration itself.

Verification evidence is prepared as part of delivery, not as an afterthought. Typical evidence covers tenant separation checks, login and logout behavior, HTTPS-only access and the version pairing in use, and it is kept with the configuration so that a later upgrade can be tested against the same checks. Ongoing support, version upgrades and continuous testing are available as retainers, which suit the quarterly Fineract release cadence and any web app changes that follow it. Ask any partner, including us, to show how a web app upgrade will be tested against your tenants before go-live, and to state in writing who applies security patches to each component.