Overview
Two-factor authentication has become a popular method of providing an additional security layer in regards to user authentication. When a user authenticates via their username and password, a secondary form of authentication is prompted where the user must enter in a unique code that is sent to the user via email or text message.
This techblog post will discuss steps on how to set up two-factor authentication for end-users within m-Power. This documentation assumes you are using Dictionary Security, and specifically validating end-users against a database table, as discussed here.
Implementation
Step 1 – Editing your Security Settings
In the m-Power developer interface, navigate to Admin -> Menu & Security -> Edit Security Settings. In the Security Settings window that appears, use the Property Options -> Text Mode to open this file (the mrcSignon2.xml) in a text editor. This file will need the following code added to the bottom, inserted right before the final </mrc_signon> tag:
<two_step_auth>
<twoFactorAuthentication pdesc="twoFactorAuthentication" value="false"/>
<sendTextEmail pdesc="sendTextEmail" value="user-choice"/>
<emailSubject pagetype="template">2FA Test from m-Power</emailSubject>
<emailBody pagetype="template">Here is your verification code: ${CODE}</emailBody>
<smsTextBody pagetype="template">Here is your verification code: ${CODE}</smsTextBody>
<expireInDays pdesc="expireInDays" value="31"/>
<user_info_table tablename="UPD2023Q2.MRCSEC1" col_user="USERID" col_email="USEREMAIL" col_phone="USERPHONE"/>
</two_step_auth>Once this block of code has been added, Save the editor and re-open the Edit Security Settings window. The Two Factor Authentication section should now be presented:
A few important notes on these properties, shown above:
- For the “Email Text” and “SMS Text Body” properties:
- This is the display text the user will be shown via SMS text and email, respectively. Each message may be modified to your liking.
- The variable ${CODE} represents the authentication code that will supplied to the user. If you do not put it in there, it will append the code to the end of the body.
- For the “Table and Column info…” property:
- Ensure this is pointing to your appropriate users table (if not MRCSEC1) and schema. Additionally, your database table must have a user id, user email, and user phone field. Make sure to specify the names of those columns.
- For the “Two Factor Expiration” property, you may enter the number of days before the two factor authentication will expire for the user:
- A value of 30 for instance, would mean thirty days before the user’s sign on will require 2FA again.
- A value of 0 means no there is no expiration date after the user’s initial 2FA.
- A value of -1 means 2FA will be prompted to the user on every sign on attempt.
If any changes were made, please make sure to save those changes and then restart Tomcat.
Step 2 – Setting up the 2FA screen
The screen that will presented to the end-user during the 2FA process is the mrcAuthentication.html file located in your dictionary folder, …/m-power/mrcjava/WEB-INF/classes/DICTIONARY, where ‘DICTONARY’ is name of your data dictionary. If this file is not within this directory, simply copy it from …/m-power/mrcjava/mrcclasses/ into your dictionary folder.
While not necessary, you may customize the style of this page to your liking, if desired. Here is an example of how that screen will look by default:
Step 3 – Add entry to web.xml file
Open the web.xml file, located in …/m-power/mrcjava/WEB-INF in a text editor and do a search for “mrc_auth2”. The following servlet must be listed in this file:
<servlet>
<servlet-name>mrc_auth2</servlet-name>
<servlet-class>mrc.TwoFactorAuthentication</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>mrc_auth2</servlet-name>
<url-pattern>/servlet/mrc.auth2</url-pattern>
</servlet-mapping>If is it not listed, please copy the above code and place this at the bottom of the file before the final tag at the very bottom of the file. Once the file has been saved, Tomcat will need to be restarted at this point.