Two Factor Authentication

Documentation

Please read this page carefully, as it contains important instructions on setting up TFA, as well as answers to common questions

By default, Two Factor Authentication is NOT enabled for all accounts. Presently there is no way to bulk set the option unless you log in as each user and enable it.

Important information:

  • Public profiles MUST be turned on for the user to activate TFA
  • TFA MUST be enabled by editing the public profile -- you cannot edit the user in the dashboard (see "Advanced use" for more info)
  • This system is not bulletproof. If a malicious person dumps your database then they will have access to the secret key and your information -- use strong passwords for everything and keep your site up to date!
  • The only way to log in if you no longer have your phone is to disable TFA via another administrator account. If you don't have a second admin account, you need to edit the database manually to disable it.
  • This addon replaces (that is deletes, then re-adds) the login page and the profile edit page to add the required functionality (due to c5's inability to override core files from packages). It is very important that you uninstall this package through the dashboard and not by deleting the files off the server. Not doing so may make your site behave strangely or not work at all. All of the original pages are restored when the package is uninstalled

Installing and activating TFA on your site / account

  1. Install the addon through the marketplace
  2. Enable public profiles (Dashboard > System & Settings)
  3. Enable TFA (Dasboard > System & Settings)
  4. Return to website and edit your profile (http://yoursite.com/index.php/profile/edit)
  5. Tick the box to enable TFA
  6. An email will be sent to the email address associated with your account. Check your spam filter if you don't receive this email
  7. Download Google Authenticator for your mobile device. If your smart phone doesn't have an app available for it, you cannot use TFA (see Advanced Use for exceptions)
  8. Open the app and scan the barcode that appears in the email. Allow images to download if you can't see it
  9. Log out once the secret has been saved, and try logging in again
  10. To deactivate TFA, log in and untick the box in your profile

Frequently Asked Questions:

Q: I have scanned in the QR code, but it keeps telling me the code is incorrect
A: Please ensure the time on your phone and the server time are synchronized. TFA allows a small drift in time (usually about two minutes) but anything outside of that will cause the wrong code to be generated

Q: I have manually added my secret key, but it tells me that the code is incorrect
A: Double check that you have entered the secret key correctly and take note of uppercase or lowercase letters. Also see the question above

Q: I didn't receive an email with my TFA details
A: First of all, check to make sure your email address is correct. Then check your spam filter -- you may need to add concrete5-noreply@yourdomain.com to your list of trusted addresses

Q: I've lost my phone / accidentally deleted my secret from my phone
A: You will need to check your email and retrieve the secret key from there. If you're unable to, get a second administrator to log in and disable TFA. If you can't, then you'll need to edit site.php. See the section below for more information

Q: I scan the QR code but it tells me that the key is not recognised
A: Try disabling TFA and enabling it again. If that still doesn't work, open a support request and tell me the name of your site (i.e. the one that appears in the title bar of your browser) and the secret key (don't worry, it's safe) 

Q: How is the QR code generated?
A: The QR code is generated using the Google Charts API. The TFA requests the code via URL and displays it. So your secret is sent to Google via HTTPS, but is never stored there. If you wish to disable the QR code, go to /packages/two_factor_authentication/libraries/authentication and edit twofactor_auth.php. Look for the getURL function (should be a third of the way down) and replace the return $encoderURL; line with return false;

 

Advanced Use

Manually adding secret keys

You can manually set up TFA on accounts without having to enable the public profile permanently. To do this you need to enable public profiles, enable TFA, then disable public profiles immediately after. After TFA has been enabled, you can edit the user through the dashboard and manually turn on TFA and set a secret key. The key needs to be base32 encoded (A-Z and 2-0 with = as padding) and must be 16 characters or longer.

If you decide to manually enable TFA for accounts you'll need to get the secret to the user somehow. The easiest way is through a QR code which can be generated through a Google URL:

https://www.google.com/chart?chs=200x200&chld=M|0&cht=qr&chl=otpauth://totp/your+site+name?secret=ABCDEFGHIJKL2345

Getting a one-time password without a smartphone

If you don't have a smartphone or are in a situation where you can't get to one, you can generate a one time password through several websites. However doing so is not recommended, as these sites are run by third parties and may store your key without your permission.

For testing I've been using http://fiddle.jshell.net/russau/ch8PK/show/ which offers a somewhat advanced interface for generating GA-compatible QR codes and the resulting TOTP. Use this site at your own risk!

Overriding Two Factor Authentication

Please note: This is meant to be used as a last resort and could put your site at risk. Where possible, keep your secret key in a second, safe location for retrieval in an emergency!

The TFA plugin has an override built in that can give you access to the site if you have lost your secret key or are unable to generate codes.

To activate the override, open /config/site.php in your Concrete5 site and add the following line at the bottom:

define("TWO_FACTOR_AUTHENTICATION_OVERRIDE", true);

Now you can log in to your site. If prompted for a verification code, leave it blank or enter in any value. Once you are logged in, turn TFA off then back on for your account in order to generate new keys.

Once you have retrieved your key, DELETE the define() line from site.php. Setting it to "false" will NOT work. You have to delete this line or your site could still be at risk.