Two-factor authentication in Cozy


Hi there,

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 :thumbsup:

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 :smile:

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/ 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.

Future improvements

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 :smile:

2FA authentification
List of available FAQ entries | Toutes les réponses

Recovery tokens

Hey there,

Just like I did last week, you may one day forget your phone at home, lose it, etc. and need to check something on your Cozy during the day. Problem: You have enabled two-factor authentication and configured it on the said phone, so the only way to authenticate through your Cozy and accessing the data it contains is by using this very same phone.

If only there was a way to log into Cozy, like a “back-up” way to access your data…

Well, one line to check off the TODO list regarding 2FA: Recovery tokens are here! Recovery tokens looks very much like the tokens you input to authenticate with your phone (or Yubikey, or whatever), just a bit longer. When you enable two-factor authentication (and any time you reset them), you are given a set of 10 one-time tokens that are stored in Cozy’s database and can be used at any time in place of your usual 2FA token.

Before we go deeper on how to use recovery tokens and where to get them, please make sure your proxy is at version 2.5.11 or higher. 2.5.10, which was the first version to implement this feature, also brought in a bug preventing you from using it. That’s the main reason explaining why I waited before writing this post, I didn’t want people to go trying the feature around and find themselves locked outside of their Cozy because of that.

Now that I made this point clear, let’s keep going.

Where do I get them?

If you browse to the bottom of your Cozy’s setting page, you’ll see the usual 2FA settings panel. Here, we have two cases.

Two-factor authentication is already enabled

Here you might see an additional text that wasn’t there before, in bold, talking about recovery tokens and followed by an error message. That’s because Cozy didn’t enabled the feature while enabling 2FA (because it didn’t know how!). All you have to do is to click the “Reset your recovery tokens” button, the page will refresh (I know, painful, but we’re working on it), and if you scroll all the way down, you’ll see numbers in place of the error. These numbers are your 10 recovery tokens.

Two-factor authentication isn’t enabled yet

Then just enable it (details about that are above), and Cozy will generate these tokens for you :wink: Hit the “Enable two-factor authentication” button, wait for the page to refresh, scroll back down, and voilà, you have some nice tokens along with all the information you need to synchronise your device.

In both cases

Make sure to copy these tokens somewhere safe (an encrypted or plain document, a paper sheet…), and make also sure that this is not on Cozy. You don’t want to lose access to your Cozy at the same time as the only way you had to recover it.

How do I use them?

Just so we’re clear on that point: Recovery tokens are one-time tokens. When you find yourself locked out of your Cozy, all alone facing the authentication page, just input your password and one of the recovery tokens just like you input your password and the token you get from your phone (or Yubikey, or… you get it).

If your token is valid, Cozy will recognise it, authenticate you and remove the used token from the list. This means that you’ll no longer be able to use this token anymore (but you’ll still have all the remaining others).

Cozy will also warn you with a notification.

You can also observe that the used token has disappeared from the list in the 2FA settings panel.

Whenever you want, either it is because you think your codes have been compromised or you have no more tokens remaining (or anything else), you can ask Cozy to replace the existing tokens with a fresh set of 10 new tokens by hitting that “Reset your recovery tokens” button. Please note that this action will disable all the previous tokens. They’ll become unusable.

And I think that’s about all there is to say on 2FA recovery tokens. We still have a lot of work ahead to make two-factor authentication in Cozy easy to understand and use on a daily basis, but we’re slowly getting closer and closer to the objective.

If you have any question, suggestions, remarks, anything that should have been said that I forgot, please feel free to share your thoughts here :smile:


Hi guys,

I’m unfortunately locked out of my Cozy and can’t get the troubleshooting trick to work. I have a full root access to the server hosting my Cozy. Here is what I see

root@someserver:~# sudo coffee /usr/local/cozy/apps/home/ cleanuser
File not found: /usr/local/cozy/apps/home/

Fine, let’s try something else

root@someserver:~# sudo coffee /usr/local/cozy/apps/home/ cleanuser
Error: expected: 204, got: 401 -- Application is not authenticated -- undefined
    at errorMaker (/usr/local/cozy/apps/home/node_modules/cozy-home/node_modules/cozydb/lib/cozymodel.js:27:13)
    at checkError (/usr/local/cozy/apps/home/node_modules/cozy-home/node_modules/cozydb/lib/cozymodel.js:18:21)
    at /usr/local/cozy/apps/home/node_modules/cozy-home/node_modules/cozydb/lib/cozymodel.js:317:16
    at parseBody (/usr/local/cozy/apps/home/node_modules/cozy-home/node_modules/cozydb/node_modules/request-json-light/main.js:75:10)
    at IncomingMessage.<anonymous> (/usr/local/cozy/apps/home/node_modules/cozy-home/node_modules/cozydb/node_modules/request-json-light/main.js:109:14)
    at emitNone (events.js:72:20)
    at IncomingMessage.emit (events.js:166:7)
    at endReadableNT (_stream_readable.js:921:12)
    at nextTickCallbackWith2Args (node.js:442:9)
    at process._tickCallback (node.js:356:17)
Cleaning Users failed.

Same punishment while not using sudo. My server runs a Debian

Too bad :cry:


Hi @Gilles, welcome aboard :smile:

The script has moved, now, on most servers, it’s path is /usr/local/cozy/apps/home/node_modules/cozy-home/, so you should try sudo coffee /usr/local/cozy/apps/home/node_modules/cozy-home/ cleanuser.

Also, there’s another way to drop the user, using cozy_management: sudo cozy_management unregister_cozy.

Let us know if one of this methods works.


Hey @Clochix,

just gave it a try. I’m running the latest stable version of cozy, updated immediately before trying your commands.

sudo coffee /usr/local/cozy/apps/home/node_modules/cozy-home/ cleanuser
Error: expected: 204, got: 401 -- Application is not authenticated -- undefined
    at errorMaker (/usr/local/cozy/apps/home/node_modules/cozy-home/node_modules/cozydb/lib/cozymodel.js:27:13)
    at checkError (/usr/local/cozy/apps/home/node_modules/cozy-home/node_modules/cozydb/lib/cozymodel.js:18:21)
    at /usr/local/cozy/apps/home/node_modules/cozy-home/node_modules/cozydb/lib/cozymodel.js:317:16
    at parseBody (/usr/local/cozy/apps/home/node_modules/cozy-home/node_modules/cozydb/node_modules/request-json-light/main.js:75:10)
    at IncomingMessage.<anonymous> (/usr/local/cozy/apps/home/node_modules/cozy-home/node_modules/cozydb/node_modules/request-json-light/main.js:109:14)
    at emitNone (events.js:72:20)
    at IncomingMessage.emit (events.js:166:7)
    at endReadableNT (_stream_readable.js:921:12)
    at nextTickCallbackWith2Args (node.js:442:9)
    at process._tickCallback (node.js:356:17)
Cleaning Users failed.

Using cozy_management proved to be successful though. I then managed to register again and found my data back :sunglasses: