2FA = Two Factor Authentication. At OSE, whenever possible, we use the following 2 factors for public-facing authentication:
- Something you know (username/password)
- Something you have (TOTP token)
For more information on 2FA, see wikipedia:Multi-factor_authentication
Adding "something you have" to the typical username/password credentials is important in case:
- A user's password is stolen (ie: phishing, not using a unique, site-specific password)
- 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:
- 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).
- 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
List of OSE Services that use 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:
- Make sure the time on your phone is accurate
- Login to wordpress, leaving the "Google Authenticator code" field blank.
- You should be automatically redirected to your profile page. If not, you may need to directly query "https://<website>/wp-admin/profile.php"
- Scroll down to "Google Authenticator Settings"
- Check the "Activate" checkbox.
- Check the "Relaxed mode" checkbox. (optional)
- Click "Create new secret", and a QR code should be displayed.
- In your phone's OTP app (FreeOTP, andOTP, etc), add a new account. Choose to scan a QR code.
- Scan the QR code given by wordpress with your phone
- 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:
- You restore your replacement phone's TOTP app with a backup that you made or
- 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.
- 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:
- 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.
- Use the oandbackup app (requires root).
- 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.