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

[MatsuShimizu]

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.

sudo snap install keepassxc

On Debian:

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.

Spoiler: Click here to view the animated GIF 1

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

Spoiler: Click here to view the animated GIF 2

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

 

[MatsuShimizu]

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.

Spoiler: Click here to watch the animated 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.

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.

Spoiler: Click here to view the diagram

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.

Spoiler: Watch the animated GIF

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.

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.

 

[MatsuShimizu]

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.

Spoiler: Click here to watch the video

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.

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.

Spoiler: Click here to watch the video

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.

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.

 

[MatsuShimizu]

Part 4: How to set up and use the Authy 2FA app

If you are new to Authy, this video can help.

Spoiler: Click to watch video

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:

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.

Spoiler: Click to view diagram

Spoiler: Click to view animated GIF - same GIF as post #2 above

 

[KGIII]

Nice.

I'll pin this for a while.

 

[MatsuShimizu]

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.

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.

 

[jrw]

And now Authy is sunset on desktop (2024/03/19). Bye, bye Authy. Hello KeepassXC!

 

[Freepoorman]

There is so much trust involved when using a password manager. Especially one with 2FA...

I created my own offline password manager using the bcrypt library with Python. It stores my passwords with unique salted hashes and bcrypt is supposed to be super slow to brute force too.

 

[CaffeineAddict]

I created my own offline password manager using the bcrypt library with Python. It stores my passwords with unique salted hashes and bcrypt is supposed to be super slow to brute force too.

No offense intended, but when it comes to cryptography and similar security concepts it's always better to use 3rd party ready to use software that is known to be audited already, because you as individual are unlikely to attract security audit experts to help discover holes in your software.

 

[Freepoorman]

No offense intended, but when it comes to cryptography and similar security concepts it's always better to use 3rd party ready to use software that is known to be audited already, because you as individual are unlikely to attract security audit experts to help discover holes in your software.

I would like to share it to anyone who would like to attempt to break it... The only reason it's not on my GitHub is because after solving encryption and workflow functionality, I lost motivation to iron out the gui and user experience bugs for now...

 

[Freepoorman]

I don't know if it's specifically relevant to Linux.org, otherwise I could create a thread and post all my code for curious users to try break it...?

 

[CaffeineAddict]

I would like to share it to anyone who would like to attempt to break it... The only reason it's not on my GitHub is because after solving encryption and workflow functionality, I lost motivation to iron out the gui and user experience bugs for now...

I totally understand, writing software on your own without contributors is a major undertaking and the biggest problem is that you become slave of your own invention because you'll have to spend a lot of your time to keep it running and prevent being deprecated due to regression.

Even some prominent experts like B. Stroustrup admitted how his entire life is dedicated to his development of C++ language standard and that he'd like to spend some of his time doing something else instead but cannot afford it due to pressure from the public.

And he is not alone, there is a ton of developers on GitHub whose software is very popular to the point where it feels like it's their job that depends on donations if any.

Very few of them succeed and make money, you really have to love your project and be ready to dedicate your time to maintain it.
I personally prefer to work on private stuff because this way nobody will pressure me with issues every day, and if I don't want to do this or that it's not problem because nobody know about it anyway.

I don't know if it's specifically relevant to Linux.org, otherwise I could create a thread and post all my code for curious users to try break it...?

I think you'll first need to make your repository very very popular in order to attract experts to performs audits on it.

It also depends on language you're using, many experts are experts in low level languages like C/C++, assembly, reverse engineering and similar languages and methods.

I suggest you learn how to write test projects and do some self-tests your self ensuring that interpreter warning are reduced to zero by conforming to language standards.
Next step after that would be using well known tools designed to spot vulnerabilities in your code, those which static analysis software cannot catch.
When that's done 3rd and final step would be to actually attempt to crack it.

 

[Freepoorman]

I totally understand, writing software on your own without contributors is a major undertaking and the biggest problem is that you become slave of your own invention because you'll have to spend a lot of your time to keep it running and prevent being deprecated due to regression.

Even some prominent experts like B. Stroustrup admitted how his entire life is dedicated to his development of C++ language standard and that he'd like to spend some of his time doing something else instead but cannot afford it due to pressure from the public.

And he is not alone, there is a ton of developers on GitHub whose software is very popular to the point where it feels like it's their job that depends on donations if any.

Very few of them succeed and make money, you really have to love your project and be ready to dedicate your time to maintain it.
I personally prefer to work on private stuff because this way nobody will pressure me with issues every day, and if I don't want to do this or that it's not problem because nobody know about it anyway.


I think you'll first need to make your repository very very popular in order to attract experts to performs audits on it.

It also depends on language you're using, many experts are experts in low level languages like C/C++, assembly, reverse engineering and similar languages and methods.

I suggest you learn how to write test projects and do some self-tests your self ensuring that interpreter warning are reduced to zero by conforming to language standards.
Next step after that would be using well known tools designed to spot vulnerabilities in your code, those which static analysis software cannot catch.
When that's done 3rd and final step would be to actually attempt to crack it.

All the code I write is either Python or Bash.. Next language I'll attempt is probably RUST. So it will likely take years for skilled pen-testers to show interest in my repository...

I'm slowly working my way through the vast ocean of knowledge towards one day getting my OSCP qualification - Hopefully I can credibly audit my own software then...

In the mean time I will try familiarize myself with the tools to spot vulnerabilities.. Do you maybe have any suggestions?

 

[CaffeineAddict]

In the mean time I will try familiarize myself with the tools to spot vulnerabilities.. Do you maybe have any suggestions?

Security auditing of a software is the elite level development because precondition is that you're already skilled with a language itself that you'll be auditing, that means having no issue to develop a software or to read and understand someones else work.
Reading and understand code of others is more difficult than understanding your own code, especially if there are no code comments in which case it feels like you need a compiler or assembler in your head to interpret it.

If one cannot develop some software then how are they going to audit someones else software?

You will get many different answers on this as to which route to take, I think you need to take your path regarding languages and dedicate yourself toward specific branch to master it.

My personal branch of interest is C++ and ASM primarily because it gives me full power over hardware and libraries and what I can do with those languages, there are rarely library limitations that would make me stuck in doing this or that because these languages are very flexible and powerful unlike some other high level languages which dictate you how you should do it, that is you have limited freedom when it comes to inventing new things or for e.g optimizing your software for performance.

You will not like my suggestion now, but if you want to become true expert you'll want to master ASM and reverse engineering as there is no limitation here, it is however most useful for cracking someones else software and to detect malicious instructions and similar.

In one video Linus Torvalds said how C language is the best language in the world, however he also admitted how he can see how his C code will translate to assembly, which suggest he's well versed in ASM as well even though it doesn't use it directly.
But the point here is that all those experts like him know ASM very well.

 

[Freepoorman]

Security auditing of a software is the elite level development because precondition is that you're already skilled with a language itself that you'll be auditing, that means having no issue to develop a software or to read and understand someones else work.
Reading and understand code of others is more difficult than understanding your own code, especially if there are no code comments in which case it feels like you need a compiler or assembler in your head to interpret it.

If one cannot develop some software then how are they going to audit someones else software?

You will get many different answers on this as to which route to take, I think you need to take your path regarding languages and dedicate yourself toward specific branch to master it.

My personal branch of interest is C++ and ASM primarily because it gives me full power over hardware and libraries and what I can do with those languages, there are rarely library limitations that would make me stuck in doing this or that because these languages are very flexible and powerful unlike some other high level languages which dictate you how you should do it, that is you have limited freedom when it comes to inventing new things or for e.g optimizing your software for performance.

You will not like my suggestion now, but if you want to become true expert you'll want to master ASM and reverse engineering as there is no limitation here, it is however most useful for cracking someones else software and to detect malicious instructions and similar.

In one video Linus Torvalds said how C language is the best language in the world, however he also admitted how he can see how his C code will translate to assembly, which suggest he's well versed in ASM as well even though it doesn't use it directly.
But the point here is that all those experts like him know ASM very well.

This is very very interesting. I will look into learning Assembly now for sure. It's so crazy I want to learn security and pen-testing as a personal long-term ambition, but at the same time I'm trying to learn more commercial languages and practices to try earn money as soon as possible. ...I guess it all adds to the final goal eventually...

I wasn't even aware of tools to audit my code before I learned that from you, I just ran a scan with Bandit for checking Python security and found a bunch of areas where there are opportunities for improvement like patching vulnerabilities for path traversal attacks and arbitrary code execution. This seems like a nice way to learn about language specific and use specific best practices.

Thank you for the advice

 

[CaffeineAddict]

This is very very interesting. I will look into learning Assembly now for sure. It's so crazy I want to learn security and pen-testing as a personal long-term ambition, but at the same time I'm trying to learn more commercial languages and practices to try earn money as soon as possible.

I'm pretty sure you won't earn much money from knowing assembly because ASM is so rarely used, today, probably the purpose of knowing ASM is to show you're garage hacker who knows how to deals with bits and bytes

And to ofc. to be able to disassemble and crack what ever you want (but not limited to this only ofc), so unless you want to know that cool skill it's probably not worth the effort because it takes much more practice than with other languages

I wasn't even aware of tools to audit my code before I learned that from you, I just ran a scan with Bandit for checking Python security and found a bunch of areas where there are opportunities for improvement like patching vulnerabilities for path traversal attacks and arbitrary code execution. This seems like a nice way to learn about language specific and use specific best practices.

Glad to hear to learned a method on how to discover vulnerabilities

 

[Freepoorman]

I'm pretty sure you won't earn much money from knowing assembly because ASM is so rarely used, today, probably the purpose of knowing ASM is to show you're garage hacker who knows how to deals with bits and bytes

And to ofc. to be able to disassemble and crack what ever you want (but not limited to this only ofc), so unless you want to know that cool skill it's probably not worth the effort because it takes much more practice than with other languages

I'm not earning anything with Python either lol. I think the money is in helpdesk and systems administration for me at the moment, so scripting helps with creating automation I guess... My real dream is doing all the cool stuff you mentioned above, just have to grind at it while I'm also still learning system administration, python, bash, and networking...

 

[tinfoil-hat]

That's an indept tutorial, will definetly take the tome read it later, thank you for your effort