Due to the number or people around here seeming lost about how to use the two-factor authentication which was added to Cozy two weeks ago, I decided to write a quick tutorial to get you started, along some troubleshooting and the next improvements we’re working on for this feature. If you have any question regarding it, this is the right place to ask!
Before I begin: Thanks all for your feedback on this feature. We now have a more precise idea of what points we have to improve, both technically and ergonomically speaking, and that’s all thanks to you and the feedback you gave us on your experience with 2FA (two-factor authentication) in Cozy. Thumbs up for an amazing community
How to enable and configure two-factor authentication (2FA)
You first need an external device to use the two-factor authentication. This can be a device specific to 2FA (such as the Yubikey or simply your own smartphone with a 2FA app installed (there are many, on many stores, such as Google Authenticator, FreeOTP, Authy or Authenticator).
Now, let’s get started. To enable 2FA, you first need to head over to the Setting page in your Cozy. At the very bottom of this page, you’ll see a space called “Two-factor authentication”:
If you don’t really care about the technical specificities of the different algorithms (aka strategies) available in Cozy, don’t pay to much attention to this form, and hit the “Enable two-factor authentication” button. In this case, you can also ignore the next paragraph (and the list that goes with it).
In the form, you’re asked to chose between two algorithms (what we also call “strategies”). There may be more in the future, but at the moment, we only support two algorithms:
- TOTP (time-based): Generates OTP (one-time passwords, a string of 6 numbers supposedly usable only once) only valid during a specific window in time (in our case, it’s around 30s). This means that a code you generate will be usable the number of times you want, but only in this 30s time window. I tend to consider this strategy as less secure (because I don’t like the ideao of an OTP being used as much as you want, even through a short period), but we set it as “default” because it’s the algorithm you’ll find on the biggest number of apps or devices.
- HOTP (counter-based): Generates OTP with no regard to time, and will associate a counter to each. For example, the first OTP you’ll generate will get the number 0, the second one will get the number 1, the third one will get the number 2, and so on. We chose to improve the security of this algorithm by adding a check on the counter: If you log in with an OTP associated to the number 707 (so the 708th OTP), then log out and try to log back in with the same code, or a code with a counter below 707, Cozy won’t let you in. I personally consider this strategy more secure, as we can make sure that an OTP is used only once.
Just chose the strategy you want to use, and click on “Enable two-factor authentication”.
Now, whether you read the explanation below or not, you must have seen the Settings page reload. This is perfectly normal.
The next step is to head back to the bottom of the page, which now looks a bit different. This is extremely important, as you can (and will) totally get locked out of your Cozy if you don’t follow the next step.
We’ll now configure your application or device. There are two elements to pay attention here: the string in bold, and the QR code.
Most of the mobile apps support QR code scanning. I know by experience that it’s the case for Google Authenticator, FreeOTP and Authy, not sure for Microsoft’s Authenticator (never had the opportunity to try it). If your app supports it, just scan the QR code displayed, and that’s it, your app is now configured to use 2FA on Cozy!
If your app doesn’t support QR code scanning, or if you use a specific device (such as the Yubikey), you’ll have to manually enter (or copy/paste) the string in bold in your app or device’s configuration panel. Some additional settings may be required, such as the algorithm/authentication type (which is displayed in the settings panel in “You are using the [algorithm] 2FA strategy”).
Configuration by either QR code or key (string in bold) is specific to the application or device, and although I wish to offer as much support as possible on all the apps possible, you must understand that I can’t cover them all here.
Now that every part is configured, you can safely log out of your Cozy. You can see that the login page now looks like this:
Just enter your password in the first field as usual. Open your mobile app and tap the “Cozy” field (or plug your device and do whatever you have to to generate an OTP), and it will give you the 6 number-long authentication code to enter in the “Authentication code” field. Now hit the “Sign in” button, and that’s it, you’re in
Specific informations for HOTP users
As I said above, when using HOTP, for each OTP, we check if the associated counter isn’t equal or below the one associated to the previous code used to log in. Which can mean problems. For example, if I change my phone, and configure my OTP app correctly, it will start generating codes with counter 0, 1, 2, etc. If I previously logged in with a code from my old phone, with counter 1242, I’ll have to generate 1244 codes for Cozy to authenticate you. And tapping 1244 times on your smartphone, each time spaced by a few seconds, it can become really long and painful. That’s why HOTP users have a specific button TOTP users doesn’t have, as you can see in the screenshot below:
The “Reset the HOTP counter” button will reset the last known counter in Cozy’s database, so it will start accepting codes from counter 0 again.
I got locked out of my Cozy
If something went wrong during the configuration, or if you lost your phone/device, or whatever reason, you can find yourself locked out of your Cozy.
If your Cozy is part of the beta infra (hosted by CozyCloud), your only way to recover access to your Cozy is by asking the team (whether by email, on this forum or on the #cozycloud IRC channel on Freenode) to reset your user access on your Cozy.
If your Cozy is self-hosted, however (which means that you can access the system hosting Cozy), you can try to reset your access by yourself following this procedure and remove the
authType field in the
User document, or with the command line
sudo coffee /usr/local/cozy/apps/home/command.coffee cleanuser
If you opt for the command line, you’ll then be asked to register again. Don’t worry, you won’t lose any data.
Here are what we’re working on right now to improve the two-factor authentication in Cozy:
Recovery tokens (tokens to use in place of an OTP in case you’ve lost your external device)
- Improvement of the activation process (what if we don’t reload the Settings page after enabling 2FA?)
- More security to prevent a third party to enable or disable 2FA (as described here)
If you have any issue or feedback regarding 2FA on Cozy, whether it’s a question, remark, suggestion or anything else, feel free to share it here