Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Page Properties


Target release
Epic
Document status
Status
titleDRAFT
Document owner 
Designer
Developers
QA


...

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. 

Project details

...

Two

...

-

...

factor authentication

...

Two-factor authentication workflow


  1. User authenticates via basic auth / Oauth2

  2. If successful, field(isTwoFactorAuthenticationRequired) indicates whether 2FA is enabled

  3. 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 TODOmethods)

  4. The 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 validate it (see Validating OTP TODO)

    1. If token is valid and hasn’t expired

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

  6. User sends the access token as a header(Fineract-Platform-TFA-Token) on every request

  7. User is allowed to have multiple two-factor access tokens:

    1. Can support multiple devices

...

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


List of configuration parameters:

NameTypeDefault ValueDescriptionNotes
Email
otp-delivery-sms-enablebooleantrueWhether 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-subjectstringFineract Two-Factor Authentication TokenEmail subject
otp-delivery-email-bodystringHello {{username}}.\n\nYour OTP login token is {{token}}.Email bodh
Sms
otp-delivery-sms-enablebooleanfalseWhether to enable the email delivery method

SMS OTP delivery requires messaging gateway and SMS external service configured.

See Message Gateway Configuration, SMS Campaigns.

otp-delivery-sms-providerint1SMS provider ID
otp-delivery-sms-textstringYour authentication token for Fineract is {{token}}.SMS text
Tokens
otp-token-lengthint

5

character length of the OTP
otp-token-live-timeint300validity time of the OTP request in seconds
access-token-live-timeint86400validity time of standard access token in seconds
access-token-live-time-extendedint604800validity 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
Anchor
api_delivery
api_delivery

Returns a list of possible OTP delivery methods for the current user

Requres first-factor authenticated user.

Example RequestExample Response
GET /api/v1/twofactor
[
    {
        "name": "sms",
        "target": "08888888888"
    },
    {
        "name": "email",
        "target": "user@example.com"
    }
]


Requesting OTP
Anchor
api_request
api_request

Requests an OTP.

Requres first-factor authenticated user.


Example RequestExample Response

POST /api/v1/twofactor?deliveryMethod=sms&extendedToken=false



Arguments:

  • deliveryMethod(string) - name of delivery method
  • extendedToken(boolean) - optional, whether to request an extended token, default false
{
    "requestTime": 1500000000000,
    "tokenLiveTimeInSec": 300,
    "extendedAccessToken": false,
    "deliveryMethod": {
        "name": "sms",
        "target": "08888888888"
    }
}

Validating OTP
Anchor
api_validate
api_validate

Validates an OTP. If the OTP is valid, an access token is created.

...

Requres first-factor authenticated user.


Example RequestExample Response

POST /api/v1/twofactor/validate?token=YYYYY


Arguments:

  • token(string) - mandatory, the OTP to validate
{
    "token": "cb0bb6e33fc540709d50a16eb2e555f9",
    "validFrom": 1501530702801,
    "validTo": 1501617102801
}

Anchor
api_configure
api_configure

Get configuration settingssettings 

Returns all two-factor configuration settings.

Requires fully authenticated user.


Example RequestExample Response

GET /api/v1/twofactor/configure

{
    "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

...

Requires fully authenticated user.


Example RequestExample Response

POST /api/v1/twofactor/configure




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



Timeline

Phase 1: May 30 - June 26
  • Fineract:
    • 2FA Configuration
    • OTP generation & verification services
Evaluation 1: June 26 - June 30

Phase 2: June 30 - July 24

Fineract:

  • OTP request & validation endpoint
  • GUID generation
  • 2FA Filter

Community-app, android-app:

  • Add 2FA login support
  • 2Fa configuration support in the community-app


Evaluation 2: July 24 - July 30

Phase 2: July 30 - August 21/29

Fineract:

  • Documentation
  • access token invalidation endpoint
  • Work on time-based 2fa(optional)

Community-app, Android client:

  • Remember me functionality