Overview
The goal of the project is to implement Two-Factor authentication for Fineract and add support for 2FA to the community-app and the Android client. With two-factor authentication enabled the system administrator will have the ability to configure how one time passwords are sent to the user - either via Email or SMS. The integration of two-factor authentication would improve the security of Fineract and its users.
During the project I will implement support for two-factor authentication into Fineract. The workflow of the process of generating and using one time passwords is described below. The existing supported front-end application(the community-app and the Android app) will be updated to support 2FA.
I would like to give as much flexibility as possible to the users and system administrator to allow for a flawless authentication without much hassle - we would allow the system administrator to select the delivery method of the one time passwords. Currently it is planned to support delivery via SMS / Email but the system should be made so it could be easily extended to support time-based one-time passwords(RFC 6238).
Project details
Two-factor authentication workflow
User authenticates via basic auth / Oauth2
If successful, field(“isTwoFactorAuthenticationRequired”) indicates whether 2FA is enabled
If 2FA is enabled, the client sends a request to get a list of available delivery methods to authenticated user(see Getting a list of delivery methods)
The client sends a request to to generate & send OTP via their selected method(see Requesting OTP)
OTP token is generated and saved in-memory
Token is sent via SMS/Email bridge
Information returned: OTP delivery method, delivery destination(email / phone number), OTP validity period
User has at most one active OTP request. If another OTP is requested, all previous OTP requests are invalidated
User receives token and the client sends it to an endpoint to validate it (see Validating OTP)
If token is valid and hasn’t expired
Information returned: access token, access token expiry time
User sends the access token as a header(Fineract-Platform-TFA-Token) on every request
User is allowed to have multiple two-factor access tokens:
Can support multiple devices
Fineract Implementation Details
Enabling Two-Factor Authentication
Two-Factor Authentication can be enabled by adding an active twofactor profile to Fineract(e.g. in application.properties or with a start parameter). -Ptwofactor=enabled parameter can be used with Gradle build job.
Configuration
Delivery methods and token parameters are configurable. Configuration is done via the configuration endpoint.
List of configuration parameters:
Name | Type | Default Value | Description | Notes |
---|---|---|---|---|
otp-delivery-sms-enable | boolean | true | Whether to enable the email delivery method | Email delivery uses Email External Service configurations for mail sending. Please configure SMTP details before using email OTP delivery. See External Services. |
otp-delivery-email-subject | string | Fineract Two-Factor Authentication Token | Email subject | |
otp-delivery-email-body | string | Hello {{username}}.\n\nYour OTP login token is {{token}}. | Email bodh | |
Sms | ||||
otp-delivery-sms-enable | boolean | false | Whether to enable the email delivery method | SMS OTP delivery requires messaging gateway and SMS external service configured. |
otp-delivery-sms-provider | int | 1 | SMS provider ID | |
otp-delivery-sms-text | string | Your authentication token for Fineract is {{token}}. | SMS text | |
Tokens | ||||
otp-token-length | int | 5 | character length of the OTP | |
otp-token-live-time | int | 300 | validity time of the OTP request in seconds | |
access-token-live-time | int | 86400 | validity time of standard access token in seconds | |
access-token-live-time-extended | int | 604800 | validity time of extended access token in seconds |
API Endpoints
There are 3 endpoints that serve two-factor authentication requests:
- /twofactor - OTP operations
- /twofactor/validate - access token generation
- /twofactor/configure - configuration
Getting delivery methods
Returns a list of possible OTP delivery methods for the current user
Requres first-factor authenticated user.
Example Request | Example Response |
---|---|
GET /api/v1/twofactor |
|
Requesting OTP
Requests an OTP.
Requres first-factor authenticated user.
Example Request | Example Response |
---|---|
POST /api/v1/twofactor?deliveryMethod=sms&extendedToken=false Arguments:
|
|
Validating OTP
Validates an OTP. If the OTP is valid, an access token is created.
The returned access token is later sent as a header Fineract-Platform-TFA-Token.
Requres first-factor authenticated user.
Example Request | Example Response |
---|---|
POST /api/v1/twofactor/validate?token=YYYYY Arguments:
|
|
Get configuration settings
Returns all two-factor configuration settings.
Requires fully authenticated user.
Example Request | Example Response |
---|---|
GET /api/v1/twofactor/configure | {
|
Update two-factor configuration settings
Update two-factor configuration.
Requires fully authenticated user.
Example Request | Example Response |
---|---|
POST /api/v1/twofactor/configure
|
|
Timeline
Phase 1: May 30 - June 26 | |
---|---|
| |
Evaluation 1: June 26 - June 30 | |
Phase 2: June 30 - July 24 | |
Fineract:
| Community-app, android-app:
|
Evaluation 2: July 24 - July 30 | |
Phase 2: July 30 - August 21/29 | |
Fineract:
| Community-app, Android client:
|