GSoC 2017 - Two-Factor Authentication

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). One of the project considerations is whether we can and should allow the user to select a delivery method if multiple are enabled. Such feature wouldn’t be hard to implement and is easily integratable into the proposed workflow but has to be discussed with the mentor.

Currently there is no way for an administrator to set up sms providers for the message gateway system nor setup tenant from an UI. One of the goals of my project is to allow setup of the sms providers from the web app. A proposed approach is given in more detail below.

Timeline

Project details

Configuration

Two-Factor Authentication would be enabled by adding an active twoauth profile to Fineract(e.g. in application.properties). With two factor authentication enabled, a system administrator can select the available delivery methods for one-time passwords via Global configurations.

Two-factor authentication workflow

1. User authenticates via basic auth / Oauth2

2. If successful, a field(e.g “tfaRequired”) indicates whether 2FA is enabled

3. If 2FA is enabled, the authenticated user sends a request to get a list of available delivery methods to him

4. The user sends a request to to generate & send OTP via their selected method

1. OTP token is generated and saved in-memory

2. Token is sent via SMS/Email bridge

3. Information returned: OTP delivery method, delivery destination(email / phone number), OTP validity period

5. User receives token and sends it to an endpoint to verify it

1. If token is valid and hasn’t expired

2. Information returned: GUID, GUID expiry time

6. User sends the GUID as a header(e.g. Fineract-Platform-OTP) on every request

7. User is allowed to have multiple GUID’s:

   1. Can support multiple devices

8. Optionally, an endpoint to invalidate GUID might be implemented

Messaging service configuration via Fineract workflow

1. Setup messaging service host, port and endpoint (1st step of configuration wizard)

2. Create a tenant in the messaging service

1. Custom endpoint in Fineract to essentially send a request to the messaging service for tenant creation- fields: tenantId & description (2nd step of configuration wizard)

3. On successful creation, save the tenant key into the external service sms configuration

4. Create an sms provider with the messaging service (3rd step of configuration wizard, skip first 2 steps if messaging gateway already set up)