Two-Factor Authentication

From SmartWiki
Jump to: navigation, search


When using Two-Factor Authentication, each new user can use the Google Authenticator app to obtain one-time passwords which are calculated from time and/or event-based algorithms. 

Most websites that a user can log into require a username and password, both "known" by the individual in order to log in. In short, this means that anyone who knows the correct username and password combination for a unique account can log into that account; thus, there is very little that can be done to identify that the individual logging is is actually the individual who owns the account. 

The Two-Factor Authentication function provides a second factor - this can be something that someone has (for example, an access card) or some unique property of that person (for example, a fingerprint, or a code sent to a personal mobile device). 

The security impact of the Two-Factor Authentication is that while a user may lose an access card or get duped into sharing a password, the odds of both happening to a single user are dramatically reduced. Using Two-Factor Authentication therefore enhances an organization's ability to ensure that no one is using illegitimate means to gain access. 

Two-Factor Authentication is a required component of maintaining SmartSimple's SOC2 security status. SmartSimple supports two different Two-Factor Authentication approaches: 

  • TOTP (Time-based One-Time Password) - this technique uses an authentication app that is installed on a mobile phone 
  • RSA Disconnected Token - this technique requires a physical device used to generate a one-time code 
This article deals specifically with the TOTP protocol. To learn more about the RSA Disconnected Token protocol and its related costs, please contact your account manager. 


In order to configure Two-Factor Authentication, you will need to have the following: 

  • System Administrator access - your user role in your SmartSimple instance must be System Administrator.
  • Access to a mobile device and the appropriate Google Authenticator application installed on the device - the app can be retrieved from Google Play, App Store, etc by searching for "Google Authenticator" in the application store. If you have not already downloaded the app onto your mobile device, please do so prior to following the steps in the rest of the article.

Configuring a Role to Use Two-Factor Authentication

Two-Factor Authentication is configured by User Role. For best practice, it is recommended to specifically create Two-Factor Authentication as a new role and add it to the existing users. While Two-Factor Authentication can be added to an existing role, it is not recommended because it will become more complex to manage. 
For roles that have this feature enabled, the use of Two-Factor Authentication becomes mandatory. This involves a drastic change in user experience, so SmartSimple recommends that this action be rolled out to users in small groups at the beginning of the process. 

The first step of the implementation process is to create this role in your SmartSimple instance

Follow the steps below in order to configure a user role to Two-Factor Authentication: 

1. Click on the 9-square menu icon on the top right of your page.

052919 MenuIcon.png 

2. Under the heading Configuration, select Roles and Security.

2factor roles.png

3. Click on the first hyperlink labelled User Roles.

The list of available user roles in your system will be displayed. 

4. Click on the + icon on the top left in order to Create a New Role. 

2factor create new user role.png 

4. The New Role page will be displayed.

2factor new role.png 

Fill out the following details: 

  • Name: 2 Factor Authentication (for clarification of the role purpose) 
  • Caption: 2 Factor Authentication (as the caption is typically the same or similar to the Name
  • Description: TOTP (for clarification of the role purpose) 

5. In the Two Factor Authentication field, click into it and select the option Time-based One-time Password (TOTP).

  • Note: If you select the None option, this means that there will be no two-factor authentication enabled for this user role. When someone with this user role tries to enter the system, they are able to successfully log in by inputting just their correct username and password combo.

6. Click the Save button at the bottom of the page.

The page will refresh with the role saved into the system.

To check that your role has been successfully added: 

1. Click the list icon in the top left row of buttons on the 2 Factor Authentication Role page. 

Return to user roles.png

2. This will bring you to the list of all user roles in the system once more. You should now see the 2 Factor Authentication role listed. 

2factor role.png

Once you see your newly created role among the list of user roles, then the role has been successfully added and is saved into the system. 

Adding Users to New Role

Once you have added the 2 Factor Authentication role (and configured TOTP in the role details), then the next step is to add existing SmartSimple users into that role.

For this process, you should remain on the 2 Factor Authentication Role page. To do so, click the pencil icon next to the role name on the list of user roles.

1. On the left-hand side will be a menu: click into the tab titled Current Users. 

2factor current users.png

2. The list of current users associated with this role will be displayed. If you have just created this role, there will be no users listed. 

Click the + icon on the top left above the list in order to Add a User to the role.

2factor add user.png

3. A list of all available users in your system will be displayed in a modal window. 

2factor add user to rolel.png 

Select which users you would like to add to the role by checking the box next to their name in the list. 

4. Click Add at the bottom of the page.

5. Any selected users will now be displayed in the list of Current Users for the 2 Factor Authentication role. 

2factor current users list.png

Activating Users with Two-Factor Authentication

After you have both added a 2 Factor Authentication role and added Users into that role, the next step is to activate those users. 

First, update the Activation Email Template in your SmartSimple system. 

1. Click on the 9-square menu icon on the top right of the page. 

052919 MenuIcon.png 

2. Under the heading Configuration, select Global Settings. 

Menu and global settings.png

3. Click into the Security tab. 

4. Under the subheading Business Security Settings, select Password and Activation Policies.

Password and activation policies global settings.png

5. Click into the second tab labelled Activation Email Templates. Ensure that the New User and Request Password templates contain an activation link (which should be denoted as https://@url@@activationlink@), and do not contain a temporary password, as in the example below: 

2factor email template.png

6. Save the template and return to the General tab in Password and Activation Policies.

7. Scroll until you find the field for Password Activation Settings - set the Activation link life span to 24 hours.

2factor activation link.png

8. Click Save. 

For the next series of steps, return to the 2 Factor Authentication role page (Roles and Security > User Roles).

1. Go into the Current Users tab from the left-hand side menu.

2. Select one or more users from the Current Users list by checking the box next to their name; the following buttons will appear: 

2factor buttons.png

Add User(s) 

+ icon

As mentioned previously, clicking this button will allow you to select from the total list of users in your SmartSimple instance to add into this role. 

Remove User(s)

- icon

Clicking this button will allow you to remove the selected user(s) from this role. 

Update Geocode

reload icon

Clicking the Update Geocode button will allow you to update the geocode (provision of geographical coordinates tied to user's inputted locations). This would be in the use-case of a contact who is using a new mobile device. 

Send Password

key icon

Clicking this button will allow you to send passwords to the selected user(s). This will trigger an activation email to the user, including their activation link for login. 

3. Click on the key icon next to Send Password to the selected users. 

Logging in with Two-Factor Authentication

Once a user has been re-activated in the system, they should receive an email with an activation link. The reason that we have re-activated these users is because they were added to the Two Factor Authentication role that specifically impacts the login and activation process into your SmartSimple system. 

The activation link their email will direct to a login screen that will display the account activation page. This screen includes fields to create and confirm a new password, CAPTCHA validation if required, and a QR code. 

Validating the QR Code

If this is the first time the user has had a code generated then the screen should include a QR Code that can be scanned using Google Authenticator. The actual authentication code is also provided in case there are issues with the use of Google Authenticator.

EnableTwoFactor 3.png

  • If the user has an existing QA Code then the user can click a button to generate a new code and re-sync or can proceed to the login page.

Users will then be prompted to enter the one-time code after entering their user name and password.

Enter your code including spaces along with your password and click Submit.

Once a user has undergone this last step of actually scanning the QR Code and inputting the generated code for authentication, they have been activated successfully with Two-Factor Authentication into your SmartSimple system. 


  • Best practice is to create a Two-Factor Authentication role and add this role to existing users.
  • Be aware that this authentication process is a complete change in user experience. We recommend testing in small batches, or on individual users, prior to applying this role to a large group of users.
  • When beginning this process, add this role to individual users for testing.
  • Codes must include spaces to correctly validate
  • Each code must be entered prior to expiry in the Authenticator app.
  • In the interest of time, it is best to complete CAPTCHA validation prior to entering Authenticator code. 
  • In the event of a user using a new device, the code can be re-generated and an activation email re-sent to the user.
  • Ensure that the email templates do not contain a temporary password - this will interfere with the activation link functionality. 
  • Make sure to re-save Activation link life-span to 24 hours during setup to give users a reasonable amount of time to log into the system, 
  • If both Single Sign-On and Two-Factor Authentication are in use, there is a Single Sign-On setting option that will control whether or not Two-Factor Authentication will be required when a user authenticates via SSO.

See Also