2FA

2FA = Two Factor Authentication. At OSE, whenever possible, we use the following 2 factors for public-facing authentication:

1. Something you know (username/password)
2. Something you have (TOTP token)

For more information on 2FA, see wikipedia:Multi-factor_authentication

Why

Adding "something you have" to the typical username/password credentials is important in case:

1. A user's password is stolen (ie: phishing, not using a unique, site-specific password)
2. A user's password is insecure (ie: set to 'password' or otherwise trivial to brute-force)

TOTP - Time-based One Time Password

TOTP (time-based one time password) tokens are the best "something you have" authentication factor. The benefits are:

1. Does not require a communication channel between the device holding the private key & the server you're authenticating other than the initial sharing of the private key. (This eliminates the risk of someone intercepting the token. 2FA systems that send tokens to users in plaintext [ie: sms messages, emails, etc] should be entirely untrusted).
2. Well-defined standard that's implemented in many FLOSS apps on many devices

For more information about TOTP, see wikipedia:Time-based_One-time_Password_Algorithm

FLOSS apps for TOTP

1. andOTP
2. FreeOTP

List of OSE Services that use 2FA

1. #Wordpress
2. #OpenVPN

Wordpress

Wordpress uses the google-authenticator and 'google-authenticator-encourage-user-activation' plugins for 2FA. For more info, see Wordpress#2FA

Quick Start Guide

If you haven't yet enabled 2FA on your wordpress account, you'll need to follow the following steps to be able to edit the site:

1. Make sure the time on your phone is accurate
2. Login to wordpress, leaving the "Google Authenticator code" field blank.
3. You should be automatically redirected to your profile page. If not, you may need to directly query "https://<website>/wp-admin/profile.php"
4. Scroll down to "Google Authenticator Settings"
5. Check the "Activate" checkbox.
6. Check the "Relaxed mode" checkbox. (optional)
7. Click "Create new secret", and a QR code should be displayed.
8. In your phone's OTP app (FreeOTP, andOTP, etc), add a new account. Choose to scan a QR code.
9. Scan the QR code given by wordpress with your phone
10. Scroll down & click "Update Profile" in wordpress.

The next time you login, you will be required to enter the token provided by your 2FA app into the "Google Authenticator code" field.

Note that until you follow the above steps, your account will be temporarily restricted to the "Subscriber" role. You'll only be able to edit your profile until you activate 2FA. You should also see this message:

This site requires two-factor authentication, which adds an extra layer of protection against hackers to your account. You'll be prevented from doing anything until you enable it, which you can do in the 'Google Authenticator Settings' section below.

If you've never used two-factor authentication before, we strongly recommend that you follow these step-by-step instructions to ensure that it is setup correctly.

What if I lose the device holding my TOTP private keys?

Great question! If you loose your phone, you will not be able to login unless:

1. You restore your replacement phone's TOTP app with a backup that you made or
2. Another admin on the site that hasn't lost thir phone logs in & edits your wp user account--unchecking the "enabled" box that you checked, so you can log back in without a 2FA token. Then you can generate a new token & scan it into your new phone as you just did.
3. Or if all admins loose their phones at the same time (or there is only 1 admin account and it's you), someone can ssh into the server & either use the wp-cli or manually delete the 'google-authenticator' plugin directory from the wordpress plugins folder (for obi it's /var/www/html/openbuildinginstitute.org/htdocs/wp-content/plugins/google-authenticator). Log in, then re-install it.

There are at least 3 ways you can backup FreeOTP:

1. The QR code you scanned is your private key. You could take a screenshot of this QR code, print a copy of it, and keep it locked in a safe. If you loose your phone, you can simply rescan your QR codes with your new phone. If you do this, be sure to shred (not just delete) the screenshot from your computer after you print it.
2. Use the oandbackup app (requires root).
3. Use the ADB = Android DeBugger CLI tool in linux to create a backup. This doesn't work for all apps, but it's been documented to work for FreeOTP at least.

       adb backup -all -apk -f backup.ab # backup all apps
       adb backup -f backup.ab org.fedorahosted.freeotp # backup just freeotp

Of course, your backups should be encrypted. If you don't know how to make secure backups, it's probably best that you just make sure that your website has multiple users (with distinct phones running a TOTP app) set as admins.

OpenVPN

The OSE OpenVPN server uses the open-source google-authenticator package from EPEL actively maintained by Google, Inc.

[root@osedev1 etc]# yum install google-authenticator
...
Installed:
  google-authenticator.x86_64 0:1.04-1.el7                                                                                                                                 

Complete!
[root@osedev1 etc]# rpm -ql google-authenticator
/usr/bin/google-authenticator
/usr/lib64/security/pam_google_authenticator.la
/usr/lib64/security/pam_google_authenticator.so
/usr/share/doc/google-authenticator-1.04
/usr/share/doc/google-authenticator-1.04/CONTRIBUTING.md
/usr/share/doc/google-authenticator/FILEFORMAT
/usr/share/doc/google-authenticator/README.md
/usr/share/doc/google-authenticator/totp.html
/usr/share/licenses/google-authenticator-1.04
/usr/share/licenses/google-authenticator-1.04/LICENSE
/usr/share/man/man1/google-authenticator.1.gz
/usr/share/man/man8/pam_google_authenticator.8.gz
[root@osedev1 etc]# 

For more information on how to setup 2FA keys for OSE Developers who want to use OpenVPN, see VPN#Sysadmin:_How_to_grant_access_to_the_dev_VPN

See Also

1. Wordpress
2. OSE Server
3. https://github.com/google/google-authenticator-libpam/