With online fraud levels ever-increasing, most if not all companies are introducing additional methods of identifying their customers. One popular approach is via a method known as two-factor authentication (or 2FA).
Two-factor authentication consists of requiring online users to identify themselves through an additional method after they’ve logged in with their standard username or password. This could be via the use of a random token generating device or app, or by sending a one-time password to the user’s email address or mobile phone.
Two-factor via an SMS token sent to a user’s mobile phone remains popular, and the cost to company and customers is minimal.
One point to be aware of though, is that the organization must be reasonably confident that the mobile number data they hold, does in fact belong to their customers. It would be prudent to create additional rule sets triggered when a customer attempts to change their mobile phone number, however this is outside the scope of this case study.
In this case study we will outline what is required to deploy a two-factor SMS authentication request seamlessly into an existing application using in-built rules that ship with Tomorrow Software.
The first step of any rule writing is to determine what to do and how it can be accomplished. Drawing flow charts can be extremely helpful.
Below is a basic example flow chart of how Tomorrow Software may implement a two-factor SMS request.
Before beginning, you will need to answer the following:
Where is the login page and where does it go to authenticate the user?
Where is the data that holds the user’s mobile phone number?
What should the rule set do if there is no mobile phone number for a user?
What are the technical details for sending SMS messages?
How long should the X Engine wait for a correct response?
How many times should the rules allow someone to enter an incorrect response and what should happen after this given amount?
This case study we will use the in-built SMS aggregator Kapow to send our messages. Your own environment may use internal SMPP calls or different aggregators, which may require you to write your own extension.
Extension writing is outside the scope of this case study but is relatively straight forward for a Java developer.
Start by creating a new repository called “Two Factor Example”.
It’s recommended that the processes involved in sending a two-factor message, checking the existence of a two-factor request and checking the response against the stored value, be separated into different rule sets. This provides ease of maintenance in the future, and also allows you to turn two-factor authentication on and off, or change out functionality quickly and easily.
So, keeping this in mind, you should create the following blank rule sets:
TwoFactorLoad – this rule set will be loaded initially and determine whether a two-factor request should be made based on the user’s login status.
TwoFactorCheck – this rule set will check whether there is an existing two-factor request in place and display the embedded two-factor response page if required.
TwoFactor – this rule set will generate the random token and embed it into the message template.
TwoFactorLookup – this rule set will look up the user’s mobile phone number from the database.
TwoFactorSend – this rule will send the message to the user’s mobile phone via Kapow.
With our two-factor authentication, we need to provide a page that will allow users to enter the token they receive via SMS. This page only needs to be very simple, with an introduction explaining what the user needs to do and a form field for them to enter their token. We will also need two additional pages:
One for an incorrect two-factor response,
And one for a two-factor time out, since the user will be given a limited time to complete the task.
Within your own web application environment, you will wish to design your pages to fit in with the site’s look and feel, but for this example we will keep it very simple.
You can use the inbuilt content editor to create your pages. to do so follow the steps below.
Expand the “Content Files” menu item and select “Two Factor Example”.
Create a new file called “twofactor.html”.
Copy the below HTML to your clipboard:
Update the "twofactor.html" file from the console. The embedded HTML editor will op
Click on the HTML button to go to the HTML text.
Paste the HTML shown above into the editor and click "Save".
The page should now look something like this:
Continue the above process for the following two files. Create new content files called:
twofactorerror.html
twofactortimeout.html
As per above, update each file, click the HTML button and paste the following HTML for each file:
twofactorerror.html
twofactortimeout.html
Save your files. Your file structure within Content Files should now look as follows:
In our example, File Reader rules will be used to read these html files. Therefore, download then upload each file separately from Content Files to the Data Files repository. All files used by File Reader rules must be accessible from the Data Files location by the X Engine.
Before we begin writing our rule sets, there is one more data file we will create. This file will be a plain text file that will contain the token and SMS message that will be sent to our users.
Begin by creating a new text document in Notepad. Copy and paste the following text into your blank document.
Your two factor token for XYZ Company is [token]. Please enter this token into our website to continue. If you are not currently logging into our website, please contact our customer service team on 01234 5678.
Save the text document as “twofactor.txt”.
Next, go to the “Data Files” section of your Tomorrow Software console. Select the “Two Factor Example” repository from the drop-down list and click the “Browse” button to select the file just created.
Next, click the “Upload” button to upload your file to the console. All files should now be saved within Data Files as follows:
As mentioned above, we have five rule sets to deal with a two-factor authentication request. Although all functionality could be contained within the one rule set, we decided to split them out into discrete chunks that all handle a different aspect of the process.
This rule set will handle looking up the user’s mobile phone number from our local database.
To begin with, use the SQL Lookup rule to look up the user’s mobile number in our USERS database. In your web applications, of course, the database, table and field names will differ, but in this example, we are using a database called USERS with a table called “Users” looking for a field called “mobile” where the field “userid” is equal to the variable “userId”.
Examine the above image to see how we have stored the result from the field “Mobile” into a variable called “MOBILE”. If the record is found, we use the If Condition rule to check that there is actually a value in the MOBILE variable – if there is, we exit the rule set with the value “Continue”. Otherwise we exit with the value “Not Found”.
You can find the Exit Rule in the “Flow” group of rules.
This rule set handles sending the token to the user’s mobile handset. This token will be set in the TwoFactor rule set in the variable we will name TOKEN.
The user’s mobile number, as you have seen, has been set in the TwoFactorLookup rule set.
We will use the File Reader rule to read the twofactor.txt file we created earlier into a variable.
Next, we will replace the token with the actual token created by our “TwoFactor” rule set by using the String Replacer rule.
Then we will use Kapow to send the message to the mobile number we found in the “TwoFactorLookup” rule set.
IMPORTANT: You will need your own Kapow username and password in the credentials vault to use the service.
Next, we exit the rule set with either “Continue” for a successful send, or “Failed” for a failed send.
This rule set will initialize a two-factor request and save the following variables to the system: a flag that a two-factor request is in progress, what the token actually is, and what the time limit is for the request.
To begin this rule set, we need to set a time stamp as an expiry and create a random token. Next, we need to pass through the TwoFactorLookup and TwoFactorSend rule sets we created earlier.
Use the Timestamp rule found in the “Variable Marking” group followed by the Calculation rule found in the “Math” group to create a time limit.
Note that timestamps are in milliseconds, so we need to add 300,000 to the current TIMESTAMP variable to get a time five minutes into the future.
Next, we will create a random numeric token by using the Random Number rule, also found in the “Variable Marking” group. Create a random number with 8 digits and save it to a variable named TOKEN.
Now we can look up the user’s mobile number and send the SMS message to their phone. To do this, use the TwoFactorLookup and TwoFactorSend rule sets from the “Rule Set” group.
We must remember to set the session variables that tell us a two-factor request has been sent, what the time limit is, and what the token is.
First though, we need to set a variable TWOFACTOR to “Y” to tell us that we are in the middle of a two-factor request. Use the Set Variable rule to do this.
Next, we can use the HTTP Session Writer rule set to assign the three variables to the session.
Finally, we need to display the two-factor response page to the user.
To do this, we must first save the HTTP request so that later on, if the user enters the correct token in a timely manner, we can restore the application to its normal flow. Use the HTTP Request Saver rule set to do this.
Next, we use the File Reader rule to read our “twofactor.html” file into a variable for display. We will call this variable RESPONSE.
Finally, we just need to display this content back to the user, followed by a Set Completed rule to tell the system not to go any further.
This rule set will check whether or not a two-factor request is in progress, and deal with any responses or timeouts the system may encounter. This rule set will use a combination of rules we have previously encountered.
The first thing to check is whether or not the time limit has passed.
To do this, we create a new timestamp called TIMESTAMP_NOW, subtract the existing TIMESTAMP from it, and if the remaining time TIME_REMAINING is greater than zero we know the two-factor session is still valid. If not, we will read the “twofactortimeout.html” file and respond back to the user.
If there’s still time left on the authentication process, we then need to check whether or not a response has been entered, and if it has, whether or not it is the correct one.
In our HTML form we set the field name to “tokenresponse” so this is the name of the variable we must check.
If there is a value, then we check it against the variable we set earlier called “TOKEN”. If there is no value, or the value is incorrect, we will use the File Reader rule to read the “twofactorerror.html” file and display back to the user.
Additionally, we will reset the TWOFACTOR variable so that the system knows not to check again.
Optionally, we may redirect the user to a specific logout page, but in this example, we will not do this.
If the user has entered the correct response, we will reset the TWOFACTOR variable to “X” so that the rule sets know that the user has already been authenticated.
Finally, we will use the HTTP Request Restorer to place the user back into the original application flow.
Lastly, we will create the TwoFactorLoad rule set which will bring together all of the previous rule sets. This rule set will determine whether or not we need to check for a two-factor request, which only needs to be done if a user has been authenticated by the system, and only on non-media content
for example, not images, stylesheets, javascript et cetera
Using the Name Splitter rule we can split the URI variable to determine the extension.
In our example we are running JSP pages, so we only want the rule set to continue if the content has the extension “jsp” and the user is currently logged in.
There are several ways to determine if a user is logged in, and which method you use will be dependent upon your specific web application. There may be a cookie or session variable that we can read, or perhaps your web application has a specific URI or query string for pages that are available to logged in users only.
In this case study we will assume that a cookie with the user’s id has been set on login.
We will use the Http Request Tracker rule to expose all cookies. The rule actually exposes all request information into separate variables, but in this case, we are only interested in the “userId” cookie.
If the userId cookie is set, then we need to check if a two-factor request is in progress, otherwise we will simply exit the rule set.
If the userId cookie is set, then we must find out whether we need to initiate a two-factor request, check a two-factor request, or ignore as the two-factor request has already been successfully processed.
First, we will use the Http Session Reader rule to place the relevant session variables into variables our rule sets can query. We will store the TWOFACTOR, TIMESTAMP and TOKEN session variables into local variables.
Next, we use the Switch rule to check the contents of the TWOFACTOR variable.
This is the variable that tells us exactly what we should do.
If the variable is not set, then we need to initiate a two-factor request. If the variable is set to “Y” then a request is already in progress, so we need to look for a token response or time out. If the variable is set to “X” then we know the user has already successfully performed the two-factor authentication, and we can pass them back to the application.
Use the “Add Chain Point” button to add the “Y” and “X” points to the Switch rule.
Then, connect each chain point to the relevant rule set (found in the “Rule Sets” group) or set completed for already authenticated users.
Before you can deploy your rule set, you need to ensure that your database server is set up correctly, assuming that you need to retrieve the user’s mobile number from an external database.
In the following example, we will connect to a MySQL database – however, the process is similar for all JDBC drivers.
The Tomorrow Software Server ships with the Derby database driver, but you can easily add new database drivers to the application. The first thing you need to ensure is that the driver to the database is available in the class path of the program or application that is running Tomorrow Software.
For the Tomorrow Software Server itself, the location is /server/lib/ext/jdbc (we recommend that you create a folder in that location named mysql and that the driver jar file is placed in there).
The MySQL JDBC driver is available from http://dev.mysql.com/downloads/connector/j/
Next, you need to create the Database Connector in Tomorrow Software by clicking the Database Connectors link on the menu.
Simply enter in the class name, URL prefix (e.g., the location of the primary server to access), username and password required to access the database.
Click “Create” and your database is ready to access.
Finally, you can set up your configuration file. Click the Configurations menu and select the “Two Factor” repository from the drop-down list. Enter some basic information about the rule to load and the databases required.
The following screen shots show the information required for the “General”, “Input Source” and “Databases” tabs.
For the “Databases” tab, click the “+” icon to add a database, type the name of your database and select our newly created MySQL driver from the list.
You can now click the “Create” button to create the configuration file. Once created, click the “Deploy” button to deploy it to the server.
The above case study shows how to implement two-factor in a specific environment, though of course each individual application will be different.
You will also need to consider how you wish to handle users for whom you do not have a mobile number – alternatives could include email, or perhaps you have some kind of external token generator.
