Skip to content

Two Factor Authentication

Jump to bottom
alsaihn edited this page Dec 18, 2018 · 2 revisions

APIS supports two-factor authentication (2FA) using FIDO U2F security tokens, TOTP Authenticator applications, and backup codes. Any combination of these methods can be used, and any number of authenticators can be added to the same account (multiple U2F keys, plus Authenticator, or just backup codes as one-time passwords). Two-factor authentication secures your account even if your password is compromised by requiring two things:

  • Something you know (your password)
  • Something you have (your security key, or phone)

Two-factor login example

U2F security keys (Physical)

If you intend to use your U2F key on Android or iOS, you will need a token that supports Bluetooth or NFC, and will need to download the Google Authenticator app.

Setting up

  1. Login to the admin interface, and click "Change Password" in the top right.
  2. Click the Two-Factor Authentication link at the bottom of the form. You may be requested to log-in again.
  3. Click "Manage U2F keys".
  4. Click "Add another key". You will be prompted to insert your security token, and press it if it has a button.
  5. If enrollment is successful, you should see an entry for your token in the table. U2F token successfully added
  6. Return to the two-factor authentication menu, and follow the link to generate backup codes. Print or write these backup codes down in a safe place.

TOTP (Authenticator) apps (Mobile Phone)

Any OATH-TOTP authenticator app is suitable for this purpose (e.g. Google Authenticator, Authy, Yubikey TOTP, LastPass TOTP, etc).

Setting up

  1. Login to the admin interface, and click "Change Password" in the top right.
  2. Click the Two-Factor Authentication link at the bottom of the form. You may be requested to log-in again.
  3. Click "Manage TOTP (Authenticator) devices".
  4. Click "Add TOTP (Authenticator) Device" and follow the prompts to scan the barcode with your app, or type the seed shown. If you are setting up from a mobile, try touching the QR code to provision your app.
  5. Once added, enter the 6-digit code that your app generates.
  6. Return to the two-factor authentication menu, and follow the link to generate backup codes. Print or write these backup codes down in a safe place.

Backup codes

Important: Backup codes are not automatically removed if you remove all other 2FA methods! Currently there is no way to remove codes completely before exhausting them. Be cautious, if you ever remove or lose your 2-Factor devices, you may not be able to log in without your sysadmin's help.

Lost tokens

If an user has lost their tokens, a backup code can be generated on the command line by running ./manage.py addbackupcode <username>.

Clone this wiki locally