Fineract maker-checker and permissions design

Why Apache Fineract maker-checker and permissions decide who can move money

A lender or savings institution should not let one staff member create a loan disbursement, change an interest rate and then approve that same change. Four-eyes control is the answer, and in Apache Fineract it has to be designed before go-live, because it determines which roles exist, which API calls wait for a second person, and how the approval queue behaves during daily operations. The Apache Fineract platform documentation covers maker-checker and role-based permissions. Confirm in the documentation for the release you will run how the feature is switched on, which state-changing requests it holds, and whether a maker can ever approve their own request.

Teams need this design when they move from a pilot to live lending or deposit operations, when several branches or back-office groups share one tenant, or when an auditor or regulator will test access. SEC guidance on internal control over financial reporting names program changes and access to programs and data as IT general control areas. The FTC Safeguards Rule requires multi-factor authentication for any individual accessing an information system unless the Qualified Individual approves an equivalent control in writing. Maker-checker works alongside those controls: it limits what one identity can complete on its own, and it leaves a record of who initiated and who approved each change. Agree the matrix of makers, checkers, administrators and exception approvers with your compliance lead before the first production tenant is provisioned, because changing roles after data exists means retesting every approval path.

DeployOpen plans and configures these controls inside your own infrastructure. That includes the role model, the permission set, the approval queue procedure and the test cases that show a maker cannot approve their own request. DeployOpen does not issue audit reports or attestations. Your independent auditor or assessor decides whether the design meets your obligations. In a written scope, ask for a list of covered endpoints, a sample of approval and rejection records exported from the command audit trail, and a walkthrough of how a checker's access is removed when a person changes roles. An assessor will usually ask for those three items first.

Maker-checker configuration options and when each fits

This table compares four ways to place approval on Fineract changes: gating whole change classes, gating above a threshold, separating maker and checker roles, and manual review outside the platform. Confirm which endpoints your Fineract version gates before choosing a row, because stronger control adds queue time and test effort. The main takeaway is that most designs combine a gated core with a documented, reviewed list of exceptions.

Option	Speed and control trade-off	Testing effort	When it fits
Approval on all changes in a class	Strongest control, but every change waits in the queue, so checker availability drives daily operations	High. Each gated endpoint needs maker, checker and rejection cases	Product, office, role and permission changes where errors are costly to reverse
Approval above a threshold	Faster for routine work. Control depends on the platform enforcing the threshold, which you must confirm	Medium to high. Each threshold boundary needs tests on both sides	Only where your Fineract version can express the threshold. Otherwise use the all-changes option
Separate maker and checker roles	No queue overhead. Control depends on role assignment, so any user holding both roles weakens it	Medium. Test that no single user can both create and approve the same change	Change classes the platform cannot gate, where staff roles can still be split
Manual review outside Fineract	Fast inside the system, but control is only as strong as the reviewer record and sampling	Low in Fineract, but reviewers need written procedures and evidence of each review	Changes Fineract cannot gate, such as direct data fixes or file-based imports, after confirming the gap
Combined model: gated core with documented exceptions	Balances speed and control, but requires a maintained exception list with owners	Medium. Test both gated paths and the exception procedure	Most multi-product deployments that need one clear audit trail across gated and reviewed changes

How to set up roles, permissions and approvals in sequence

This sequence turns a written control matrix into working maker-checker roles in Fineract, with each step verified before the next one starts. The result is evidence that approvals are enforced by the platform and recorded in an audit trail that names both the maker and the checker.

Write the control matrix first
Before touching the Fineract configuration, list every state-changing command that money or customer data depends on, such as loan disbursement, savings withdrawal, charge waivers, client status changes and journal adjustments. For each one, record who may initiate it, who must approve it, the threshold or condition that triggers a second person, and the business owner who signs off the matrix. The output is a signed matrix that the configuration will be tested against. Check: every command in the matrix has a named maker role, a named checker role and an owner, and no command is left as an open question.
Define roles and fine-grained permission sets
Translate the matrix into Fineract roles and permission sets, keeping maker and checker rights in separate roles so that no single role can both create and approve the same command. Map each permission to the API operation it governs, and remove broad administrative rights from operational roles. Confirm the exact permission names and their behavior against the Fineract version you run, since the documentation and source are the authority here. Check: a review of the role export shows that no role holds both maker and checker rights for the same command, and the owner of the matrix has approved the mapping.
Create separate maker and checker test users
Create at least one test user for each side of every approval path, assigning each user only the role defined for that side. Use distinct accounts for the maker and the checker rather than shared logins, and keep the default development credentials out of any environment that holds realistic test data. Record which person controls each test account so that later audit entries can be traced back to a human. Check: each test user can perform only the actions in its role, and a login attempt with the wrong role fails as expected.
Enable approval on the agreed commands
Turn on maker-checker for the commands in the signed matrix, changing one command group at a time so that each change can be tested and rolled back if needed. Record the configuration change, the date and the person who made it. Where a command has conditions, such as amount thresholds, confirm that the condition is set as documented rather than assumed. Check: submitting each approval-enabled command as the maker creates a pending request in the approval queue and does not change the underlying record until a checker acts.
Run the approval queue end to end
Using the test users, submit a request as the maker, review it in the approval queue as the checker, and approve it, then repeat with rejection. Confirm that the record changes only after approval and that a rejected request leaves the record untouched. Also test edits to a pending request, and confirm they are either blocked or handled as the matrix specifies. Check: each command in the matrix completes the full path of submit, approve and reject, with the expected record state at every point.
Run negative tests for self-approval
Attempt the control failures that auditors ask about: a maker approving their own request, a user without checker rights approving a request, a checker editing the request before approving it, and a user with two roles acting in both capacities for one item. Each attempt should be refused by the platform, and the refusal should be logged. Document each test case with the input, the expected result and the actual result. Check: every negative case is refused, and any case that succeeds is treated as a defect and fixed before the configuration goes further.
Confirm the audit log records both actors
Review the command audit trail for the approved and rejected test requests, and confirm it records the maker who submitted each request, the checker who acted on it, the command, the time and the outcome. Export or retrieve the entries the same way an auditor would, and check that they can be matched to the test cases from the previous step. Confirm with your platform team how the trail is retained and where it is stored, since that is a deployment decision. Check: every test request appears in the audit trail with both actors identified, and the test evidence package is filed with the control matrix.

Role design for branch, credit, operations and finance teams

Branch staff capture client records, loan and savings applications, and cash transactions at the counter. Their maker role should create and edit the records they are accountable for, but it should not carry the authority to approve those records or to change the products, charges and codes that drive them. Keep branch permissions narrow enough that one teller cannot move money or alter configuration from the same login.

Capture only: Allow creation and edits of client and application data, but withhold approval rights for loans and withdrawals.
No configuration rights: Keep product, charge, code and office setup with platform or finance administrators.
Office scoping: Limit each user to their own branch where your tenant and role model supports it, and confirm how that scoping behaves in your version.
Named logins: Prohibit shared branch accounts so every action in the command audit trail traces to one person.

Confirm in a test tenant that a branch user cannot approve a submission they created before go-live.

Security and operational considerations for four-eyes control

Four-eyes control is only as strong as the accounts, credentials and tenant boundaries behind it. The cards below cover the security settings that decide whether a maker-checker design holds up under audit and in daily operations.

Shared accounts break attribution

A shared login lets one person create a change and another person approve it under the same identity, so the audit trail cannot show two separate people. Give every maker and checker a named Fineract user, and confirm in your own tests that each command is recorded against the individual who submitted or approved it. Review any service account used by integrations so that it cannot approve its own submissions.

Default development credentials

The Fineract README documents a default development login, and it must be changed before any real deployment. Leaving it in place gives anyone who knows the default full access to the approval queue. Rotate the credential as part of the build, remove the default account from production tenants, and check every tenant you create.

Choosing OAuth2 or basic authentication

The README shows both OAuth2 and HTTP basic authentication. Basic authentication sends credentials with every request, so it suits only tightly controlled service paths, while OAuth2 ties sessions to an identity provider that can enforce password policy, disable leavers and support multi-factor sign-in. Decide per user group which method applies, and confirm how the choice affects the maker and checker roles you define.

Enforcing HTTPS-only access

Approval requests and their payloads carry customer and loan data, so plain HTTP exposes both credentials and content. The Fineract documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Set this on every instance, including read and batch instances, and test that plain HTTP requests are refused at the gateway.

Keeping tenants separate

Fineract is multi-tenant, and each API request names its tenant with the Fineract-Platform-TenantId header. A request that targets the wrong tenant can approve or view another institution's pending work, so treat the header as a security boundary. Verify that the gateway or client sets it from a trusted source, and test that a checker in one tenant cannot act on a queue in another.

Monitoring the approval queue

Pending approvals can sit unnoticed for days, and stale requests create operational and fraud risk. Set an owner for the queue, alert on items that exceed an agreed age, and review approvals that a checker has granted in bulk or outside working hours. Ask your team to confirm how the queue is reported in their chosen Fineract version, since reporting features differ between releases.

Questions buyers ask about Fineract maker-checker and permissions

How much effort does designing maker-checker controls in Fineract take?

The effort depends mostly on how many state-changing workflows need four-eyes control and how many distinct roles your organization runs. Each workflow needs a decision on who may create the change, who may approve it, whether the same person can ever do both, and what happens to a pending request when its data changes. Design work also includes mapping staff roles to Fineract permissions, which is where most of the iteration happens because real job functions rarely match a standard set. Ask any partner to show the control matrix for your scope before agreeing on effort, and confirm with the Fineract documentation for your release how approval and permission features behave, since details can differ between versions.

How long does configuration and testing usually take for approval workflows?

Duration follows scope. A single approval path for one product type is a much smaller job than a full matrix covering client, loan, savings, accounting and administrative changes across several offices. Testing usually takes as long as configuration, because each approval path needs positive and negative cases, including attempts to approve one's own entry, approvals after a record has changed, and roles that should be blocked. Fineract's release cadence also matters: the project publishes quarterly releases, so a timeline should state which release it targets and whether a later upgrade is planned. Request a written schedule tied to a defined control list rather than a generic duration.

What does our team need to supply before the control design starts?

Three inputs shape almost everything: named policy owners who can decide which transactions require approval and at what thresholds, a role matrix that lists job functions, branches and the actions each function must and must not perform, and representative test data that reflects real products, offices and edge cases such as reversals and closures. Without policy owners, the design stalls on questions that only the business can answer. Without a role matrix, permissions get granted by habit and later fail review. Without test data, approval paths are verified only against clean examples. Your compliance lead should also confirm which evidence formats the internal audit function accepts before the build begins.

Can an internal team design and run maker-checker in Fineract without a partner?

Yes, a capable internal team can design and configure these controls, provided it has engineers who know the Fineract API and permission model, staff who own the policy decisions, and time for independent testing. The work that most often needs outside help is verification: a second pair of eyes checking that every state-changing endpoint is covered, that no role can bypass approval through a less obvious route, and that the audit trail records what an examiner will ask about. Many organizations split the work, keeping policy ownership and operations in-house while using a partner for design review and testing. Whichever model you choose, document who is accountable for each control.

What evidence will an auditor ask for to prove four-eyes control works?

Auditors typically ask for the written control design, the list of transactions placed under maker-checker, the role matrix showing who holds create and approve rights, and samples of completed requests showing a maker and a different checker for each sampled item. They will also test exceptions: whether any role could approve its own work, whether changes made after approval are caught, and whether administrators can alter permissions without a logged trail. Your audit trail must show who initiated, who approved or rejected, and when, so keep Fineract's audit records and access logs under retention rules you can demonstrate. DeployOpen prepares systems, controls and evidence for assessments, but independent auditors issue any opinion.

How do we confirm the approval and permission behavior for our Fineract release?

Start with the Fineract documentation for the exact version you plan to run, then test the behavior in a non-production tenant before relying on it. Check which endpoints support approval, how permissions are named and grouped, what the approval queue displays, and what the audit records contain. Because the project releases quarterly and archives end-of-life versions, confirm that your chosen release is still supported at go-live and that a planned upgrade will not silently change permission outcomes. Record the results of this check as part of your control evidence, since it shows the design was verified against the real software rather than assumed.

Does a maker-checker design need to change when we add or retire products?

Yes. Every new loan product, savings product, office or role introduces transactions that either fall under an existing approval rule or need a new one. Treat the control list as a governed document with an owner, a change log and a review step, and run the approval test cases again after any product or permission change. Teams that skip this step often discover that a new workflow quietly bypasses approval because it uses an endpoint nobody added to the design. Ask any partner how they plan to support ongoing reviews, and whether that work sits under a fixed-scope project or a support retainer.

Limits to confirm in your Fineract version before you commit

Maker-checker design depends on details that vary by release and deployment, so the controls you plan on paper may not match what the platform does. The cards below list the items to test in your target Fineract version before you fix the approval design, the staffing model and the evidence you will hand to auditors.

Endpoints that support approval

Not every state-changing endpoint in Fineract routes through an approval step in every release. Build a matrix of the loan, savings, client, accounting and configuration endpoints you intend to gate, and confirm for each one whether the maker request is held, whether a checker can approve or reject it, and whether the approved action is then executed exactly as submitted. Record the result against the release you will deploy, not against the documentation for a later version.

Expiry and reassignment of pending requests

Ask what happens to a pending request that no checker picks up. Confirm whether requests expire, how long they remain open, whether an administrator can reassign them, and whether a maker can withdraw or resubmit a request that has gone stale. Unresolved requests can pile up in the queue or be approved long after the underlying facts changed, so the operating procedure should define ownership and escalation before go-live.

Approvals inside batch requests

If your integrations send batch requests, confirm whether each sub-request is subject to the same maker-checker rules as a single call, and whether a batch can mix gated and ungated operations. A batch that bypasses approval for one of its items is a control gap. Test partial failures as well, since one rejected item should not leave the rest of the batch in an unclear state.

Export of the command audit trail

Confirm how the command record is stored, which fields identify the maker, the checker, the request payload and the timestamps, and whether the record can be exported in a form an auditor can sample without database access. Check retention, whether records can be altered by administrators, and how the trail is protected when a tenant is removed or restored. Also confirm whether logs of authentication and permission changes are kept alongside it.

Role and permission model

Confirm which permission codes exist in your release, which are granular enough to separate creating, approving and administering each product, and whether a single user can hold both maker and checker rights for the same entity. Verify how permission changes are themselves approved and logged. Overlapping role grants are a common source of segregation of duties failures found in review.

Mapping to your regulator's expectations

Fineract can provide the technical control, but the control design must match what your supervisor, external auditor or certification body expects for segregation of duties and change management. Take your control narrative to those parties before build, and ask them which evidence they will sample. DeployOpen prepares systems, controls and evidence for assessments but does not issue audit reports, attestations or certifications, and independent auditors make that determination.

How DeployOpen scopes and delivers Fineract four-eyes control

DeployOpen plans, implements, hardens and documents self-hosted Fineract inside your own infrastructure, including the maker-checker rules, role design and command audit trail described on this page. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

Inventory every state-changing Fineract API and classify which ones need a second approver.
Map your staff roles, approval limits and segregation-of-duties conflicts into a written permission model.
Define the approval queue behavior, escalation paths and audit evidence your auditors will request, in the written scope.

How we build

Configure maker-checker settings and fine-grained permissions in a non-production tenant first.
Test maker and checker separation with scripted cases covering rejected, edited and expired approvals.
Verify that the command audit trail records who made, approved and executed each change, and that it can be exported.

How we hand over

Deliver a permission matrix, approval rule register and runbook your operations and risk teams can maintain.
Document how to add roles, change approval thresholds and review access without weakening separation of duties.
Walk your staff through the approval queue and audit trail so they can answer control questions unaided.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover.
Retest the permission model after each Fineract release, using the release cadence in the project documentation as a planning input.
Ask your DeployOpen contact to confirm retainer scope, response expectations and review cycles in the quote.

Apache Fineract maker-checker and permissions