In-depth tutorial: How to set up 2FA TOTP with KeepassXC, Aegis and Authy.

MatsuShimizu

Well-Known Member
Joined
Jan 14, 2021
Messages
403
Reaction score
583
Credits
8,788
I have wanted to write this tutorial for more than 2 months now, but just don't have time to do it before this. Glad I could finish it this week.

In case you didn't know, KeepassXC is an open-source, cross-platform password manager but it can also be used as a 2FA app. Once I use KeepassXC as my 2FA app, I was able to stop using most 2FA apps on smartphones like Google Authenticator. This tutorial will guide you through the process.

This tutorial consists of 4 parts:
I posted each part of this tutorial on a different post for easy navigation.

Part 1: Getting started with KeepassXC.
Part 2: How to use KeepassXC for 2FA TOTP. If you already knew how to use KeepassXC, this one is for you. Scroll down to post #2 or click here.
Part 3: How to transfer from Google Authenticator to Aegis or other 2FA apps. Scroll down to post #3 or click here.
Part 4: How to set up and use the Authy app. Authy app is a cross-platform 2FA app. Scroll down to post #4 or click here.
Part 5: Troubleshooting and more tricks. Scroll down to post #5 or click here.

My experience of using 2FA apps on both Linux desktop and smartphone
- From experience, I figure out that using 2FA apps on Linux Desktop like Authy or KeepassXC is much easier and safer rather than using 2FA apps via smartphone.
- What did I mean by safer? The problem with Google Authenticator is if I lose the phone, I need to use the backup codes and reset back my 2FA settings. If I lose both 2FA backup codes and my phone, I will lose the entire account.
- With KeepassXC, I can backup my 2FA accounts into a USB drive. As for Authy, my accounts are backed up in the cloud so it is safe.
- Storing your 2FA TOTPs in a password manager is not a bad thing most of the time. It will keep things simple but secure as it should be. More details here.

General tips about 2FA:
- Some websites might ask for your phone number if you don't have 2FA activated. In this case, you have no choice but to use 2FA apps like KeepassXC or Authy rather than giving them your real phone number.
- For other websites like forums, you can use a password manager with strong, unique passwords. In most cases, you don't need to activate the 2FA on forums if you already used a password manager with strong, unique passwords for all your online account. Read the details here: Do I need 2 factor authentication if I use a password manager - Discussion on Quora.
- Important: Please write the one-time backup codes on a piece of paper. If you lose the 2FA device and your backup codes and secret keys, you will lose the entire account.

Part 1: Getting started with KeepassXC
If you are new to using KeepassXC, watch this video first.


Installation:
KeepassXC is available for Ubuntu, Debian, Arch, Gentoo and more.

On Ubuntu:
I prefer using snap because it is more secure according to their documentation.

Code:
sudo snap install keepassxc

On Debian:
Code:
sudo apt-get install keepassxc

On other distros:
Read on the official website here for details: https://keepassxc.org/download/#linux

Pros of using KeepassXC as password manager:
- You can set an easy-to-memorize password as your database master password. It is safe as long as you keep the KDBX database offline.
- It comes with a TOTP function, password generator, password strength meter function, the ability to assign a specific icon for any type of password.
Cons of using KeepassXC as password manager:
- If your house gets burned, you will lose your passwords, unless you backup the database somewhere else.
- The database is stored locally on your PC, so you must back it up into a USB drive now and then.

If you don't have the time to backup your passwords, you can use an online password manager like Bitwarden or Lastpass. Watch this tutorial on Password Bits on how to get started with Bitwarden.

General tips about password manager:
- Use strong, randomly generated passwords for your online accounts. A strong password must contain at least 20 characters with random characters.
- Use the KeepassXC password generator to generate and measure the strength of your password.
- The KeepassXC password generator/strength meter is the best so far when compared to other password strength meters I've found on search engines. If the password shows excellent on the KeepassXC strength meter, it will pass other password strength testing sites. Watch the animated GIFs below for demonstrations.
If the GIF image is not clear, click on it to enlarge.
keepassxc-passwordstrengthmeter3.gif

I don't use my real password on the above GIF image. It is just a randomly generated password.
keepassxc-password-strength-meter2.gif

Related sources:
KeepassXC support forum at Github: Click here
KeepassXC homepage: keepassxc.org
KeepassXC browser extension: For Firefox here | For Chrome here
 
Last edited:


Part 2: Using KeepassXC as the 2FA app
If you prefer watching a video, watch the video (animated GIF) by clicking the spoiler button below to see how it is done.
If the GIF image is not clear, click on it to enlarge.
keepassxc-totptest.gif

Real case study: Using KeepassXC TOTP with Twitter account
In this tutorial, I use Twitter as an example. Other online accounts like Facebook or Youtube account are similar to this example.
Just so you know, the secret key, QR code, and backup codes below are not taken directly from a real Twitter account. I generated those somewhere else and then edited the screenshots below.

Step 1: Setting up TOTP from KeepassXC.
(1) Log in to the Twitter account.
(2) From the left menu > More > Settings and privacy > Security and account access > Security > Two-factor authentication > Two-factor authentication > Check authentication app.
(3) You will get a menu Authentication app > Start > Enter password. A QR code appears > Click the link "Can't scan QR code"?
(4) Copy the secret key from Twitter.
(5) Open your KeepassXC KDBX database. Right-click on any entry > TOTP > Set up TOTP.
(6) Paste the secret key into KeepassXC. Click OK. In this example, the secret key is BAIM32FJEP2E2DZH. You can try that yourself on KeepassXC.
(7) Save the KDBX database.

The diagram below demonstrates the process above.
p2step1.png


Step 2: Setting up with Twitter.
Once you've saved the secret key (Step 1 above), your TOTP will be generated every 30 seconds.
(1) To view the TOTP, right-click on the entry > TOTP > Show TOTP.
(2) You will get the TOTP code. Click copy.
(3) Back to Twitter. Click next from the existing page
(4) Then paste the TOTP code from (2) and then click verify.
(5) Important: Write the one-time recovery codes/backup codes on paper.
The diagram below demonstrates the process above.
p2step2.png

KeepassXC 2FA tips
Tip #1: Transfering the 2FA account from KeepassXC to Authy for Desktop.
If you are new to Authy, refer to post #4 on this thread.

How to transfer from KeepassXC to Authy:
(1) Save the secret key in the KeepassXC entry first.
(2) Back up the KeepassXC KDBX database into your USB drive first before trying this.
(3) Right-click on the entry > TOTP > Setup TOTP.
(4) Grab the secret key and paste it into Authy Desktop App.

If you prefer watching a video, click the spoiler button below.
keepassxc2authy.gif
p2tip1.png


Tip #2: Transfering the 2FA account from KeepassXC to Aegis or Google Authenticator.
(1) Select the entry that contains the secret key/TOTP.
(2) Right-click > Select TOTP > Show QR Code.
(3) A QR code will be displayed.
(4) Scan this code with Aegis or Google Authenticator on your smartphone.
(5) Once scanned, Google Authenticator or Aegis will generate the same TOTP code as KeepassXC.
p2tip2.png


Tip #3: Keep the secret key into the Bitwarden Vault
If you have a Bitwarden account, you can transfer the secret key from KeepassXC into Bitwarden.
If you are using Bitwarden free account, your 2FA TOTP won't be activated. But at least you can keep the secret key somewhere safe rather than losing it. Should you lose your KeepassXC database, at least you have a backup.

Steps:
Make sure that you already saved a secret key in KeepassXC entry.

- Back up the KeepassXC KDBX database into your USB drive first before trying this.
- Always keep your secret key encrypted no matter where you choose to save it.


Right-click on the entry > TOTP > Set up TOTP.
(1) Select the secret key > Copy.
(2) Then, click cancel.
(3) Paste into the Bitwarden item/entry.
p2tip3.png
 
Last edited:
Part 3: How to migrate from Google Authenticator to Aegis 2FA app or other 2FA apps
Tip:
  • Not many 2FA apps can transfer from Google Authenticator via the QR code. Google Authenticator QR codes can be scanned and transferred only to Aegis and Google Authenticator itself so far based on my experiment. It worked for me at least by the time I wrote this post.
  • Authy, AuthPass didn't work on the Google Authenticator QR code. I tried those and didn't work.
  • I downloaded the Aegis .apk file via F-Droid, install the app, scanned and it worked for me.

Reminder: Do not uninstall the Google Authenticator for at least 6 months. The reason is your account might still be connected to the 2FA codes in the Google Authenticator. If you still want to do so, make sure that you keep the one-time backup codes on paper.

Introduction to Aegis 2FA app
Homepage: https://getaegis.app/
The video below is not needed to most people, but some might find it useful.

How to migrate from Google Authenticator to Aegis:

1. Download the Aegis 2FA app. F-Droid version here. Google Play version here.
2. Scan your Google Authenticator QR code with the Aegis 2FA app.

On the first phone, open the Google Authenticator app:
Three dots at the top-right > Transfer accounts > Export accounts > Password > Select accounts > Select all accounts > A QR code will be displayed.

On the second phone:

Tap the (+) icon on Aegis > Scan QR code > Scan the QR code from Google Authenticator from the first phone.

p3step1.png

The image is taken from a video below. Credit to the creator

3. Aegis will save your online accounts.
4. With the Aegis 2FA app, you can export to another 2FA app, like KeepassXC, Authy, or Bitwarden.


How to export from Aegis to KeepassXC 2FA app
(1) Touch and hold on to the account that you want to export.
(2) Click the edit icon. (The pencil icon).
(3) Tap advanced.
(4) Tap the eye button to view the secret key.
(5) Type the secret key to the KeepassXC 2FA app like above.
(6) Click OK and save when you are done.

p3step2.png


How to export from Aegis to a .JSON file or text file

(1) Open the Aegis app > Tap the 3 dots icon on top-right.
(2) Settings > Import and export > Export.
(3) Choose the format and encryption level. (.JSON, or text file).

For details about 2FA with KeepassXC, please refer to the post #2 above on this thread.
 
Last edited:
Part 4: How to set up and use the Authy 2FA app
If you are new to Authy, this video can help.
I can not find a Youtube video on how to use Authy on Linux. So the video below is about using Authy on Android and Windows. But the interface and setup process is the same as Authy for Linux.

General tips:
- Unlike Google Authenticator, with Authy, your 2FA accounts will be synced and stored online, so should you lose your phone, there will always be a backup online.
- Your Authy accounts will be linked with your phone number.
- If you are new to Authy, please write the one-time recovery codes/backup codes on a piece of paper. Keep the paper with you for at least one year. While there could be a backup online, anything can happen.

Authy installation:
Authy is a cross-platform app. For installation on Linux, run the following command line:

Code:
sudo snap install authy

If the above command line doesn't work, please refer to this website: https://snapcraft.io/authy
For installation details on all platforms, including iOS and Android, refer to the official Authy website: https://authy.com/download

How to transfer from KeepassXC to Authy:
- Make sure the entry contains your secret key. Save the database first.
- Back up the KeepassXC KDBX database into your USB drive first before trying this.
Then, follow the diagram below.
p4authy.png
keepassxc2authy.gif
 
Last edited:
Nice.

I'll pin this for a while.
 
KeepassXC troubleshooting and additional tips
How to recover a password or a secret key from KeepassXC.
If you already saved the password or TOTP secret keys, but somehow you've deleted the password from the entry, you have the option to recover it back.
(1) Select and entry, edit it. Then, click on History.
(2) Select a previous entry from the history section.
(3) Click Show or Restore.
(4) Click OK to restore the entry.

history-step1.png

Aegis 2FA troubleshooting
If the 2FA TOTP code displayed on Aegis is not the same as your first device, most likely it is due to the time on your second device/second phone. You need to adjust the time on your second phone, so it is the same as the first phone.
Authy troubleshooting
By default, Authy doesn't back up your 2FA codes online. You need to turn on the backup function from the settings in the Authy app. Then enter the backup password.
 


Top