Two Factor Authentication (2FA or TFA) Implementation
Shanmugam Radhakrishnan (Deactivated)
Teresa Gracias
Hanisha Potturi (Deactivated)
Purpose and Benefits
2FA is additional security mechanism to protect the user from fraudulent act. Bahmni uses basic authentication (username, password) from OpenMRS so far. However, it is optimal to have additional security mechanisms to protect users from fraudulent acts. Thus we are introducing 2FA in Bahmni. This feature is optional for an implementation. When this feature is enabled then the user will be authenticated with username and password first and on success, the user will get an SMS with an OTP to his/her registered mobile. The user has to authenticate with the OTP before proceeding to use the system.
The generated OTPs use Java's SecureRandom (see details of the implementation here). The OTPs and all operations like generation, validation, expiry are handled in memory only. There is no database involved.
Steps
1. Enable/disable 2FA
To enable/disable 2FA, add the following snippet in the /etc/bahmni-installer/setup.yml file before Bahmni installation.
two_factor_auth: enabled/disabled
2. Add SMS gateway service
Bahmni gives flexibility add SMS gateway service to the implementer.
Please refer bahmni-sms-plugins for more info.
3. Add user's mobile number
Add the user's mobile number to the OpenMRS database.
The contact table is present in the OpenMRS database. It has 3 columns.
- user_name must be exactly the same as the username in OpenMRS.
country_code can be found here.
Country_code should not contain the preceding "+"
mobile_number is the mobile number of that user.
If reports module is installed, then for reports-user 'bypass2fa' role should be added to OpenMRS.
insert into contact(user_name, country_code, mobile_number) values('Leo','91','9955273623');
4. Check Audit Logs
Every event is captured in the audit log. The log file will be created every day, but only recent files from the past 90 days are kept.
Location of Audit Logs
Audit logs are located at /var/log/bahmni-two-factor-auth/audit-logs directory
Sample log entries:
- OTP 623704 generated for doctor1
- Failed attempt #1 using OTP 123131 by doctor1
- OTP 623704 validation successful for doctor1
5. Override OTP configurations
These settings can be overridden by adding configuration to the application.properties file.
Location of application properties file
application.properties is located at /home/bahmni/.bahmni-security directory
Property | Description | Default Value |
---|---|---|
OTP_LENGTH | Number of digits in the generated OTP | 6 |
OTP_EXPIRES_AFTER | Number of minutes the OTP should be valid after it is generated | 15 |
OTP_MAX_ATTEMPTS | Number of times the user is allowed to enter a wrong OTP, before the user is redirected to the login screen | 3 |
OTP_MAX_RESEND_ATTEMPTS | Number of times the user can request a new OTP by clicking on resend button, before the user is redirected to the login screen | 3 |
The Bahmni documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)