Cosmic Module

O

Qubits of DPK

March 23, 2026

Core Open Source
Layer: Layer 7 — Communication & Security

What This Module Is (Big Picture)

The two-factor authentication module adds an extra layer of security to the system.
Instead of relying only on a password, the system requires a second verification step.
This step usually involves sending a one-time password (OTP) to the user.
The user must enter the OTP to complete authentication.

Layman Example

A bank employee logs into the system.
Step 1
Enter username and password.
Step 2
System sends an OTP to the user’s phone.
Example message:
plain text
QUBITS OF DPK
1Your verification code is 482913
Step 3
User enters the OTP.
Only after verification is the login successful.
The fineract-twofactor module manages this authentication process.

Where the Code Lives

Key Package

org.apache.fineract.infrastructure.security.twofactor
Responsibilities include:
  • generating OTP codes
  • sending OTP messages
  • validating OTP codes
  • managing authentication sessions

Core Domain Entity:

TwoFactorAuthenticationRequest.java

Path
fineract-twofactor/src/main/java/org/apache/fineract/infrastructure/security/twofactor/domain/TwoFactorAuthenticationRequest.java
This entity represents an OTP authentication request.

Key fields on

TwoFactorAuthenticationRequest

OTP Generation

The module generates random numeric codes.
Example OTP:
482913
OTP rules typically include:
  • numeric code
  • short validity period
  • single-use verification

Example OTP Generation Code

plain text
QUBITS OF DPK
1public String generateOtp() {
2
3    Random random = new Random();
4    int otp = 100000 + random.nextInt(900000);
5
6    return String.valueOf(otp);
7}
This generates a 6-digit OTP.

OTP Validation

When a user enters an OTP, the system checks:
  • whether the OTP matches
  • whether the OTP is expired
  • whether the OTP has already been used

Example OTP Validation Code

plain text
QUBITS OF DPK
1public boolean validateOtp(String enteredOtp, String storedOtp, LocalDateTime expiry) {
2
3    if (LocalDateTime.now().isAfter(expiry)) {
4        return false;
5    }
6
7    return enteredOtp.equals(storedOtp);
8}
This verifies the OTP before allowing login.

API Layer

Main controller
TwoFactorApiResource
Example endpoints
plain text
QUBITS OF DPK
1POST /v1/twofactor/request
2POST /v1/twofactor/validate
These APIs allow:
  • requesting an OTP
  • validating an OTP

Read Services

Read services retrieve authentication requests.
Examples include:
  • retrieving pending OTP requests
  • checking OTP expiration
These are used during login validation.

Write Services

Write services manage OTP authentication.
Responsibilities include:
  • generating OTP codes
  • storing OTP requests
  • validating OTP responses
  • marking OTPs as used

Repository Layer

Exceptions

These ensure authentication remains secure.

How It All Connects (Full Flow)

Example: User login with two-factor authentication
plain text
QUBITS OF DPK
1User Login
2    │ Username + password
3    ▼
4Authentication Service
5    │ Generate OTP
6    ▼
7SMS Service
8    │ Send OTP message
9    ▼
10User enters OTP
11    ▼
12TwoFactorAuthenticationService
13    │ Validate OTP
14    ▼
15User authenticated

Why This Module Matters

Two-factor authentication improves system security by:
  • preventing unauthorized access
  • protecting sensitive operations
  • adding an extra verification layer
This is essential for financial systems handling sensitive data.

One-Sentence Summary

fineract-twofactor provides an additional authentication layer using OTP verification to secure user access to the system.

Connection to BFF Proposal

Your FINERACT-2439 BFF will have its own auth layer (Spring Authorization Server). Understanding twofactor shows you the existing auth patterns Fineract uses.