Page Comparison

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.

...

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

...

• Fineract:
  • 2FA Configuration
  • OTP generation & verification services
  • Test suite

...

Phase 2: June 30 - July 24

...

Fineract:

• OTP request & validation endpoint
• GUID generation
• 2FA Filter
• Documentation
• Test suite

...

Community-app:

• Add 2FA support to the http service
• Create after-login page for 2FA

...

Evaluation 2: July 24 - July 30

...

Android app:

...

...

Community-app:

• messaging gateway configuration via config wizard

Project details

Configuration

Two-Factor Authentication would can be enabled by adding an active twoauth twofactor profile to Fineract(e.g. in applicationin application.properties or with a start parameter). -Ptwofactor=enabled parameter can be used with Gradle build job.

With two factor authentication enabled, a system administrator can select the available delivery methods for one-time passwords via Global configurationsaddtional configurations can be made via the two-factor configuration endpoint. More information on configuring two-factor authentication is given below(TODO).

Two-factor authentication workflow

1. User authenticates via basic auth / Oauth2

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

3. If 2FA is enabled, the authenticated user client sends a request to get a list of available delivery methods to him authenticated user(see Getting a list of delivery methods TODO)

4. The user client sends a request to to generate & send OTP via their selected method(see Requesting OTP TODO)

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

4. User has at most one active OTP request. If another OTP is requested, all previous OTP requests are invalidated

5. User receives token and the client sends it to an endpoint to verify itvalidate it (see Validating OTP TODO)

1. If token is valid and hasn’t expired

2. Information returned: GUIDaccess token, GUID access token expiry time

6. User sends the GUID access token as a header(e.g. Fineract-Platform-OTPTFA-Token) on every request

7. User is allowed to have multiple GUID’stwo-factor access tokens:

   1. Can support multiple devices

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

Messaging service configuration via Fineract workflow

...

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

...

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)

...

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

...

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 paremeters are configurable. Configuration is done via the configuration endpoint.

List of configuration parameters:

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.

[
    {
        "name": "sms",
        "target": "08888888888"
    },
    {
        "name": "email",
        "target": "user@example.com"
    }
]

Requesting OTP

Requests an OTP.

Requres first-factor authenticated user.

{
    "requestTime": 1500000000000,
    "tokenLiveTimeInSec": 300,
    "extendedAccessToken": false,
    "deliveryMethod": {
        "name": "sms",
        "target": "08888888888"
    }
}

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.

{
    "token": "cb0bb6e33fc540709d50a16eb2e555f9",
    "validFrom": 1501530702801,
    "validTo": 1501617102801
}

Get configuration settings

Returns all two-factor configuration settings.

Requires fully authenticated user.

{

    "otp-delivery-email-body": "Hello {{username}}.\n\nYour OTP login token is {{token}}.",
    "otp-delivery-sms-enable": true,
    "otp-delivery-sms-provider": 6,
    "otp-delivery-email-subject": "Fineract Two-Factor Authentication Token",
    "otp-token-length": 5,
    "access-token-live-time-extended": 604800,
    "otp-delivery-email-enable": true,
    "otp-token-live-time": 300,
    "otp-delivery-sms-text": "Your authentication token for Fineract is {{token}}. das",
    "access-token-live-time": 86400
}

Update two-factor configuration settings

Update two-factor configuration.

Requires fully authenticated user.

{
    "otp-delivery-sms-provider": 7
    "otp-delivery-sms-enable": false
}

{
    "changes": {
        "otp-delivery-sms-enable": false,
        "otp-delivery-sms-provider": 7
    }
}

Timeline