Duo 2FA

This page discusses options for two-factor authentication at the University of Waterloo. See IST's page on options.

U2F Token

Hardware devices such as Yubikeys can be used with Duo. Note that these may have compatibility issues in some cases, such as authenticating for the university's VPN and some third-party email clients.

Duo Mobile App

This is what the school recommends. After setting up, there are two options for authenticating using the Duo mobile app:

1. While online, you can receive a push to your device and approve the sign-in that way.
2. While offline or online, you can generate a code to use to authenticate. (This option has been disabled for most services. It is still possible to use these codes for e.g., connecting to the university VPN but not for authenticating through the web portal.)

This second option actually uses HOTP under-the-hood.

HOTP

HOTP authentication has been disabled for most services. Make sure you have another option set up.

After registration (which must be performed while online), the Duo mobile app can be used purely offline with HOTP. With a bit of finagling, you can instead register using third-party software, obtain the HOTP secret, and then load this secret into the HOTP-supporting 2FA client of your choice, such as GNOME Authenticator for Linux, Aegis Authenticator for Android, or FreeOTP for Android and iOS.

duolibre

One approach to getting the HOTP secret is to use duolibre.

(I had trouble getting duo-hotp to work recently and am updating this guide to use duolibre instead.)

1. Download duolibre

As of 2023/10/26, the version of duolibre on PyPI does not support the QR code approach used here. ( GitHub issue) Clone duolibre from GitHub instead:

git clone https://github.com/evan-goode/duolibre

cd into the duolibre directory.

2. Install dependencies

duolibre requires the Python packages click, pycryptodome, pyotp, qrcode, and requests.

On Debian: sudo apt install python3-click python3-pyotp python3-qrcode python3-requests (You will need to additionally install pycryptodome. The python3-pycryptodome package in Debian provides pycryptodomex and will not work, see https://www.pycryptodome.org/src/installation. Alternatively, install python3-pycryptodome and run sed -i 's/Crypto./Cryptodome./g' /path/to/duolibre/duolibre/duolibre.py.)

On Fedora: sudo dnf install python3-click python3-crypto python3-pyotp python3-qrcode python3-requests

From pip: pip install --user -r requirements.txt

(See https://pip.pypa.io/en/stable/installation/ for how to install pip if you need it.)

3. Add a device and get your HOTP secret

In a web browser, head to https://2fa.uwaterloo.ca/duo/enrol if you have not enrolled yet or https://2fa.uwaterloo.ca/duo/dmp if you have already enrolled and are adding a new device. Start the Duo setup. When it asks which type of device you're adding, select Tablet.

Duo will ask what type of tablet you're adding. Select Android.

Duo setup will ask you to install Duo Mobile for Android. Say you have it installed.

Duo setup will ask you to activate Duo Mobile for Android. Right-click on the QR code and copy the image location.

Now, cd into /path/to/duolibre/duolibre/ and run ./duolibre.py 'https://<image URL>' to register with Duo. You must be online during this step so duolibre can talk to Duo.

duolibre should negotiate your shared secret with Duo and output it to the terminal. It should look something like this:

Fetched secret: b'<YOUR SECRET>'
Provisioning URI is: otpauth://hotp/Duolibre?secret=<YOUR SECRET>&counter=1

This is your HOTP secret. You can enter this into a 2FA program to generate your Duo codes.

This should also output a QR code you can scan to add this secret to your 2FA app.

You should now be able to click Continue on the Duo setup.

Other possible options (to investigate)

DuOTP for Android might be an option for getting the HOTP secret. Has anyone successfully used DuOTP?

SMS/Phone call

This appears to be an option, but it is not recommended.