Apache Fineract API gateway and WAF setup

Why Apache Fineract needs an API gateway and WAF before go-live

A gateway and WAF are the controls that decide what reaches Fineract at all. Fineract is a headless application with REST APIs and no user interface of its own, so every staff tool, partner integration and any customer app reaches it over HTTP. Without an edge layer, the set of reachable endpoints is whatever the application exposes, and the request path into the loan and savings ledger is the same path an attacker would take. An API gateway enforces a route allow-list so only the endpoints each consumer needs are published, applies rate limits per consumer, and writes access logs that incident responders can search. A web application firewall adds injection filtering, including SQL injection rules, in front of those routes. The project's README warns that production deployments are complex and that it does not provide a comprehensive production deployment guide, so the edge is a place where you must design controls the project does not hand you.

The need is strongest when Fineract serves more than one kind of caller. Staff tools, partner systems and any customer-facing channel should each get a separate route set, and the gateway is where that separation is written down and tested. Teams should confirm three things before choosing a product: which paths each consumer must reach, which methods and content types each path accepts, and whether the platform will send the Fineract-Platform-TenantId header that the multi-tenant design depends on. Logging needs the same care. Record the tenant, the consumer identity and the request path for every call, and confirm that the log store is separate from the Fineract database so an intrusion there does not erase the trail.

The gateway does not replace authorization inside Fineract. A route allow-list can block a path, but it cannot decide whether a given staff user may approve a loan, read another office's clients or bypass a maker-checker step, because those decisions depend on Fineract's own roles, permissions and tenant scope. Treat the edge as a reduction of exposure and a source of evidence, not as the access control itself. The default mifos login must also be replaced before any traffic passes the edge, since a gateway in front of a known credential protects very little.

Choosing between Apache APISIX and Kong for the gateway

Apache APISIX is a top-level Apache Software Foundation project licensed under Apache-2.0, built on NGINX and etcd, with dynamic routing and hot-loaded configuration and plugins. Its documentation describes more than 100 built-in plugins, and its openid-connect plugin is part of the open source project, which matters if you want token validation at the edge without buying an enterprise tier. APISIX supports traditional, decoupled and standalone deployment modes, so the same route design can run with etcd-backed control or as a file-driven configuration.

Licensing fit: The gateway and its openid-connect plugin are Apache-2.0, so the license terms for your edge stack are simple to document for review.
Deployment modes: Traditional mode listens on port 9080 for client traffic and 9180 for the Admin API, while decoupled and standalone modes separate or remove etcd.
Standalone configuration: In file-driven standalone mode, APISIX checks conf/apisix.yaml or conf/apisix.json every second and hot-reloads, which suits version-controlled route allow-lists.
Release currency: The downloads page lists APISIX 3.19.0 (September 28, 2026) and the APISIX Ingress Controller 2.2.0 (August 18, 2026), with no long-term support label.
Operational ownership: etcd, the Admin API and the plugin runners are components your team must secure, back up and patch.

Confirm current release status, support windows and any commercial support terms directly with the project and your vendor before selecting a version for production.

Gateway and WAF configuration options and when each fits

This table compares the gateway deployment modes, WAF and rule settings, and logging choices for a Fineract edge, with the trade-off for each. Read each row as a decision: find the option that matches your change process and your need for runtime control, then check the trade-off before you commit.

Decision	Option	Trade-off and when it fits
APISIX deployment mode	Traditional (data and control plane together, etcd)	Simplest topology with the Admin API on port 9180 and client traffic on 9080. Fits a single site with a small team that can run etcd and accepts that config changes go through the Admin API.
APISIX deployment mode	Decoupled (separate data and control planes sharing one etcd cluster)	Separates the exposed data plane from the management plane, which suits a DMZ layout. Adds etcd and network paths to operate and secure between the planes.
APISIX deployment mode	Standalone (file-driven, no etcd)	Routes live in conf/apisix.yaml or conf/apisix.json, checked every second and hot-reloaded. Fits git-reviewed, change-controlled route sets, but there is no dynamic API for runtime edits, so every change is a reviewed file change.
Kong deployment topology	DB-less (configuration held in memory)	Declarative config loaded without a database. Fits a fixed, reviewed route allow-list, but every node needs the same config source and runtime edits are not persisted.
Kong deployment topology	Hybrid (separate control and data planes)	Control plane manages config for data planes in other zones. Fits multi-zone estates, but adds certificate trust between planes and a second tier to patch. Kong Gateway Enterprise version support applies to the Enterprise build.
Route allow-lists	Explicit path and method rules, deny by default	Only the Fineract paths your front ends need are published, with GET, POST or PUT limited per route. Requires a complete inventory of Fineract endpoints and a review each time a new module is enabled.
Route allow-lists	Broad prefix routes with WAF filtering	Simpler to maintain, but any new or self-service endpoint is reachable by default. Only suitable when the WAF and authorization layers are tested against that wider surface.
SQL injection rules	Managed WAF rule set in blocking mode	Blocks known injection patterns at the edge. Pattern matching does not replace fixes in Fineract, so confirm rule coverage against the query parameters used by search and report endpoints.
SQL injection rules	Custom rules tuned to your API schema	Narrower false positives on known parameters and fields. Needs ongoing tuning and test traffic for each release of the API.
Rate limits	Per client identity (OAuth2 subject or API key)	Limits follow the caller, which suits partner integrations. Requires the gateway to see a stable identity, so confirm how the token or header reaches it.
Rate limits	Per tenant (Fineract-Platform-TenantId header)	Stops one tenant from exhausting shared capacity. Needs the tenant header to be validated at the edge, since a client can set any value.
Rate limits	Per route, with stricter limits on write and batch endpoints	Protects expensive operations such as batch requests and report runs. Limits may need tuning against normal branch peaks.
Self-service endpoints	Blocked at the gateway (deny route)	Keeps self-service APIs out of reach until a separate component with its own authorization is in place. Fits the default posture recommended for exposed deployments.
Self-service endpoints	Detect-only mode in the WAF	Logs matching traffic without stopping it, useful for a short baseline period. Leaves the endpoint reachable, so it should not be the final state.
Logging destinations	Local files with forwarding to a SIEM	Keeps records if the SIEM is down and fits small teams. Confirm retention, time sync and integrity controls on the host.
Logging destinations	Direct export to a SIEM or log platform	Central search for incident response, with the trade-off that exporter failure or volume can lose events. Confirm buffering and alerting on pipeline health.

Setting up the gateway, allow-lists and WAF in order

This sequence puts a deny-by-default edge in front of a non-production Fineract, tests each control in detect mode before enforcing it, and ends with logs that an incident responder can use. Each step closes with a check so that no control moves forward on assumption.

Inventory every Fineract path consumers need
Work with the teams that call Fineract to list each REST path, HTTP method, calling system and the role that uses it. Include batch endpoints, reporting endpoints, file uploads and any callbacks Fineract makes outward. Group the list by consumer so that each route has an owner who can approve changes later. Done means every route in the inventory has a named consumer and a stated reason, and the list is signed off before any gateway configuration begins. Anything without an owner stays out of the allow-list.
Build a deny-by-default route allow-list
Configure the gateway so that every request is rejected unless it matches a route from the inventory. Match on method and path, not on path prefix alone, so that a permitted read path cannot be used to reach a write or administrative path beneath it. Store the allow-list as version-controlled configuration that a second engineer reviews. The check is a request to a path that is not in the inventory, which must return a denial from the gateway and never reach Fineract.
Place the gateway in front of a non-production Fineract
Deploy the gateway chosen for the project in a non-production environment and point its upstream at a Fineract instance that holds no real client data. Confirm the default ports for the chosen product in its documentation, for example the APISIX ports 9080 for client traffic and 9180 for the Admin API, or the Kong quick start ports 8000, 8001 and 8002, and keep the admin interfaces off public networks. Configure the gateway to require the Fineract-Platform-TenantId header, reject requests without it, and forward it unchanged. The check is a tenant-scoped request that reaches the correct tenant, and a request without the header that is denied.
Add WAF rules and test them in detect mode
Enable SQL injection rules and the other managed or custom rules your WAF supports, and set them to log matches without blocking. Replay known-good traffic from the inventory and a set of attack payloads against the search and report paths, which are the likeliest injection points. Review each match and tune rules that fire on legitimate requests, such as report filters containing quoted text. Confirm the rule set and its version with your WAF vendor. The check is a documented list of rules with the false-positive rate you observed in your own test traffic, with each exception recorded.
Enable rate limits per route and consumer
Apply rate limits to authentication endpoints, search and report endpoints, and bulk operations, keyed by consumer identity where the gateway can read it and by source address where it cannot. Set the initial thresholds from observed traffic in the test environment, not from assumed values, and confirm the limit behaviour with the team that operates the consumer. The check is a load test that exceeds a threshold and receives the gateway's limit response, while normal consumer traffic below the threshold is unaffected.
Block self-service and administrative paths
Explicitly deny the self-service and administrative paths that the allow-list does not need, including any self-service endpoints the Fineract project advises keeping disabled. Record each denied path with the reason it is blocked so that a future request to enable it goes through the same review as a new route. Confirm the denial in both detect and block configurations. The check is a request to each blocked path that returns a denial and produces a log entry naming the matched rule.
Switch the WAF and gateway rules to block mode
After the detect-mode matches have been reviewed and tuned, change the rules that should stop traffic to block mode, starting with the injection rules and the deny rules. Keep the rate limit and allow-list changes in a single change record with a rollback step that restores the previous configuration. Repeat the replay tests from the detect phase against the new configuration. The check is that the same attack payloads now return denials, that the known-good traffic still passes, and that the rollback procedure has been run once in the test environment.
Wire gateway and WAF logs for incident response
Send gateway access logs, WAF rule matches, rate limit events and denied requests to the log platform your security team uses, with timestamps, route names, consumer identifiers, tenant headers and the rule that matched. Confirm the logs leave the gateway host and cannot be altered by the gateway's own administrators. Agree retention with the security and compliance owners before go-live. The check is an investigation exercise in which a responder traces one simulated attack from the WAF match, through the denied request, to the consumer and tenant involved.

Which Fineract endpoints the edge should block and why

Not every route Fineract exposes should reach the internet, and the edge is the place to decide that before traffic reaches the application. The cards below group the endpoint classes that deserve a deny or restrict rule, with the reason for each and what to verify in your own deployment.

Self-service APIs stay disabled

The Fineract project advises leaving self-service APIs disabled, so the gateway should deny those paths outright rather than rely on the application to refuse them. Customer-facing functions belong in a separate component with its own authorization. Confirm with your Fineract version's documentation which self-service routes exist, then test that each one returns a denial from the edge, not a login prompt.

Administrative and configuration endpoints

Endpoints that change tenants, users, roles, product setup or system configuration are high-impact targets. Restrict them to a named administrative network path, such as a VPN or bastion range, and require strong authentication on that path. Build an inventory of administrative route prefixes from your deployment, and confirm that a request from a general client address is refused before it reaches the application.

Report and search endpoints

Report and search endpoints accept user-influenced filters and parameters, which makes them the places where injection risk concentrates. Keep them behind authenticated routes, apply WAF SQL injection rules with logging first and blocking second, and review what parameters each route accepts. Ask your team to list every report and search parameter so that WAF tuning does not create blind spots.

Batch endpoints

Batch requests combine many operations into one call, so a single request can perform many writes and bypass per-request rate limits that count calls rather than operations. Decide whether your product needs batch access from outside your network at all. If it does, limit it to trusted callers, set a maximum payload size at the gateway, and confirm that the audit trail still records each contained operation.

Default-credential login paths

Fineract's README shows a development login that must be changed for any real deployment, and a leftover default account gives an attacker a known username and password. Block any login path that is not needed by your users, and rate limit the remaining authentication routes. Before go-live, test that the default credentials fail at the application and that repeated failed attempts are logged and throttled at the edge.

Security and operational considerations at the edge

The gateway and WAF are only as trustworthy as the way they are administered, updated and observed. The cards below cover the controls that keep the edge from becoming a new attack surface, and the operational habits that keep it correct over time.

Keep the admin API off public networks

APISIX listens on port 9180 for its Admin API in traditional mode, and anyone who reaches that interface can change routes, plugins and upstreams. Bind it to a management network, restrict access by source address, and confirm that no public load balancer forwards to it. Test the exposure from outside your perimeter rather than assuming the firewall rule is in place.

Protect gateway credentials and plugin secrets

Gateway admin keys, OpenID Connect client secrets and upstream credentials for Fineract must not sit in route files committed to source control or in container images. Load them from your secrets manager at runtime, rotate the admin key on a schedule and after staff changes, and restrict who can read the configuration store. Ask your team to list every plugin that holds a secret and where that secret is kept.

Do not trust the WAF alone for injection

A WAF with SQL injection rules reduces noise and blocks known attack patterns, but it cannot judge every query path Fineract exposes. Treat the WAF as a compensating layer and keep Fineract on releases that carry its own SQL injection fixes, including the 1.15.0 fixes listed in the security reports. Review which fixes are back-ported to your branch, because a WAF signature does not replace a patched application.

Handle logs as personal data

Gateway and WAF logs capture request paths, headers and sometimes bodies, and Fineract requests can carry client names, identifiers and KYC details. Decide which fields are redacted before they leave the gateway, such as Authorization headers and request bodies on onboarding endpoints. Set retention that matches your records policy, restrict who can search the logs, and confirm the logs reach your SIEM without copying raw personal data into tickets.

Version gateway and WAF rules

Route allow-lists, rate limits and WAF exceptions change often during an incident or a Fineract upgrade. Store them as declarative files in Git, require review before merge, and deploy them through the same pipeline used for the application. Every exception should carry an owner and an expiry date, so a temporary bypass cannot quietly become permanent.

Track gateway release support

APISIX 3.19.0 was released on September 28, 2026, and the downloads page does not mark any release as long-term support, so plan upgrades on your own cycle. Kong's open source line and its Enterprise releases follow different support windows, which affects which OpenID Connect features you can use. Confirm the support end date for your chosen version before go-live and record it in your patch calendar.

Questions teams ask before putting Fineract behind a gateway

What drives the cost and effort of putting Fineract behind a gateway and WAF?

The main cost driver is how many routes, clients and environments the edge must serve, not the gateway software itself, which is open source in the case of Apache APISIX. Effort rises with the number of Fineract API families you expose, the number of front ends and partner systems that call Fineract, the identity model you must integrate with, and how much logging and alerting your security operations team expects. Costs fall into two groups. One-time work covers architecture, route allow-list design, WAF rule tuning, test runs and runbooks. Recurring work covers patching the gateway, reviewing WAF false positives, rotating certificates and reviewing logs. Ask any provider for a quote that lists each route group, each environment, each identity integration and each log destination as separate line items, with the owner of every item stated.

How long does a gateway and WAF project for Fineract usually take?

Duration depends on scope, and no supplied figure gives a standard timeline, so treat any number from a vendor as a claim to verify. A single internal environment with a fixed list of routes and one identity provider is much shorter than a multi-region rollout with partner integrations, separate tenant routing and a security operations integration. The longest phases are usually route inventory, because teams often discover undocumented callers, and WAF tuning, because rules that block legitimate requests must be found in staging with real traffic patterns. Ask for a written plan with phases, entry and exit criteria for each phase, and the dates that depend on your change-approval calendar and your test copy of data.

What must our team provide before the gateway work starts?

The work needs four inputs from your side. First, network access: the subnets, load balancers and DNS zones where the gateway sits, plus firewall rules that allow the gateway to reach Fineract instances and nothing else. Second, identity: the OAuth2 or OIDC provider, client registrations and the token claims your applications use, as covered by the Fineract authentication choice. Third, a log platform that accepts gateway and WAF events, with retention that your incident response policy requires. Fourth, a test copy of data and a staging Fineract environment that matches production routes, so rules can be tuned without touching live accounts. Confirm early who owns each input, because most schedule slips come from a missing approval rather than from technical work.

Can our in-house team build the gateway and WAF without a partner?

A capable platform or security team can do this work, provided it has people with experience in reverse proxies, TLS, identity protocols and WAF rule tuning, and time to test against a Fineract copy. The points where in-house teams most often need outside help are route allow-list design across a large API surface, tuning SQL injection rules without breaking report and search endpoints, and writing a runbook that the on-call team can use during an incident. Decide with a short skills review: list who will own the gateway after go-live, how many hours per month they can give to patching and rule review, and whether they have tested an allow-list against real callers. A partner is most useful when the internal team needs a documented design and a verified handover.

Is a WAF alone enough to protect Fineract?

No. A WAF inspects requests for patterns such as SQL injection, but it does not replace route control, authentication, authorization or tenant isolation. Fineract requires a Fineract-Platform-TenantId header, so the edge should check that requests target the tenants and paths the caller is permitted to use. A WAF can also miss attacks that stay within allowed syntax, and it cannot tell whether a valid token belongs to the account being read. Use the WAF as one layer with a default-deny route list, rate limits on sensitive paths, blocking of self-service and test endpoints, and logging that feeds incident response. Fineract's own self-service APIs should remain disabled unless an isolated component with its own authorization fronts them.

How does the gateway choice affect future Fineract upgrades?

The gateway choice affects upgrades mostly through the routes and plugins you build, not through Fineract itself. Route definitions, authentication plugins and WAF rules must be retested whenever Fineract changes its endpoints, so keep them in version control with a test suite that runs against each target release. Apache APISIX is released under Apache-2.0 and offers traditional, decoupled and standalone deployment modes, and its openid-connect plugin supports common identity providers. Kong's open-source repository is also Apache-2.0 licensed, but its OpenID Connect plugin is an Enterprise tier feature, which changes the licensing and support model. Check which plugins you need against the license tier before choosing, and confirm which release lines receive security fixes, since the Kong Gateway Enterprise support policy and the APISIX downloads page each publish their own release status.

What DeployOpen delivers for the edge

The edge work package produces a written configuration that DeployOpen builds and tests inside your own cloud account, data center or private network. It starts with a route inventory that lists every Fineract path your clients, staff tools and integrations call, grouped by the instance type that serves it (write, batch or read). From that inventory, DeployOpen drafts the route allow-list for the gateway, the WAF rule set and the rate limits, and records which routes are deliberately blocked, including self-service endpoints. You review and sign off each row before anything is deployed, so the scope is fixed in writing before work starts.

The gateway and WAF configuration is delivered as version-controlled files that run in your environment, with the gateway deployment mode, the TLS termination point and the Fineract-Platform-TenantId handling documented for your team. DeployOpen tests the allow-list and WAF rules against the running stack and hands over the test evidence: which requests were expected to pass, which were expected to be rejected, and the observed results. Confirm with your security team which tests they need to see, and whether they want the evidence in a format their assurance process already accepts.

Logging is the last deliverable. Gateway access logs, WAF events and blocked-request records are forwarded to the log platform you operate, with fields that let an incident responder tie an edge event to a Fineract user and tenant. Handover covers an operations runbook, the change procedure for rule updates, and a session where your engineers run the rule update process themselves. Ask in your quote whether ongoing rule tuning, gateway upgrades and retained testing are included or sold as a separate retainer, because those costs recur after go-live.

How DeployOpen scopes and delivers Fineract edge security

DeployOpen plans, implements, hardens and documents the edge in front of a self-hosted Apache Fineract deployment inside your own infrastructure. The work starts from a written scope, so route allow-lists, WAF rules, rate limits and logging are agreed with your security and banking operations teams before any configuration changes.

How we scope

Inventory every Fineract route your front end, partners and staff tools call, and mark which paths stay blocked.
Agree the gateway product, deployment mode and hosting location in the written scope before build starts.
Define which self-service and test endpoints are blocked at the edge, and who approves any exception.

How we build

Configure the gateway with route allow-lists, authentication handling, TLS termination and rate limits for each tenant path.
Tune WAF rules for SQL injection and other injection classes, testing each rule against recorded Fineract traffic in staging.
Build configuration as version-controlled files so every gateway and rule change has a reviewable history.

How we hand over

Test allow-list and blocking behavior, rate limits and WAF rules, and record the results as evidence for your reviewers.
Document routes, rule sets, log fields and retention settings in a runbook your operations team can follow.
Walk your engineers through change, rollback and incident steps, including how to export edge logs to your SIEM.

How we support

Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.
Ongoing gateway upgrades, rule updates and continuous testing are available as a retainer.
Confirm with your team which gateway release line and support window apply before you commit to a version.

Putting Apache Fineract behind an API gateway and WAF