Skip to main content

Two-factor authentication (2FA): troubleshooting

To protect your home, every Gladys Plus account is secured with two-factor authentication (2FA): in addition to your password, Gladys Plus asks for a 6-digit code generated by an authenticator app on your phone (Google Authenticator, Microsoft Authenticator, 2FAS, Ente Auth...). This code changes every 30 seconds.

This code is asked when you log in on plus.gladysassistant.com, when you connect your local Gladys instance to Gladys Plus (in Settings > Gladys Plus of your instance), and for a few sensitive actions (generating recovery codes, changing your 2FA app, resetting your password).

This page lists the most common problems, and how to solve them.

My 2FA code is refused​

If Gladys shows "Two Factor code is invalid", check the following points one by one: in the vast majority of cases, the problem is one of them.

1. The time on your phone is wrong​

2FA codes are computed from the current time. If the clock of your phone is off by more than about 30 seconds, all the codes it generates are refused, even though they look perfectly fine.

Make sure your phone sets its date and time automatically:

  • iPhone: Settings > General > Date & Time > turn on "Set Automatically".
  • Android: Settings > System > Date & time > turn on "Set time automatically" (the exact menu can vary depending on the brand of your phone).

Then try again with a new code. Only the clock of your phone matters: the clock of your Gladys instance has no impact on 2FA codes.

2. You are using the wrong entry in your authenticator app​

If you configured 2FA several times (for example after a reset, or when testing), your authenticator app may contain several entries related to Gladys. Only the most recent one works: the older ones generate codes that are refused.

Try the codes of each Gladys entry, one after the other. Once you found the right one, you can delete the obsolete Gladys entries of this same account from your app, to avoid any confusion. Keep the entries of your other Gladys Plus accounts, if you have several.

Also check that you are logging in with the right email address: each Gladys Plus account has its own 2FA.

3. The code expired while you were typing it​

A code is only valid for a short time. If the code is about to change (most apps show a small timer), wait for the next code and enter it right away.

4. The code was not entered correctly​

The code is made of 6 digits, without space. Some apps display the code as 123 456: type the 6 digits without the space. If you copy and paste the code, make sure no space or extra character was copied.

5. Too many attempts​

After several wrong codes in a row, Gladys Plus may temporarily refuse new attempts ("Too many failed attempts"). Wait a few minutes, then try again with a new code.

I changed phone or reinstalled my authenticator app​

2FA codes are generated from a secret stored in your authenticator app. If you change phone, or uninstall the app, this secret only follows you if your app synchronizes or backs up your accounts: otherwise, the new app won't generate valid codes.

First, check if your app can restore your accounts​

Some authenticator apps save your accounts online: for example Google Authenticator when it is linked to your Google account, Microsoft Authenticator with its cloud backup, Ente Auth, or 2FAS with its backup. Install the same app on your new phone, then sign in or restore the backup. If your Gladys entry comes back, its codes work as before: you have nothing else to do.

Otherwise, it depends on whether you still have your old phone.

You still have your old phone​

That's the easiest case. You have two options:

  • Transfer your accounts from the old app to the new one, using the export feature of your authenticator app (most of them offer one, for example "Transfer accounts" in Google Authenticator).
  • Register your new app on Gladys Plus: log in on plus.gladysassistant.com, go to Settings > Security, and click on "Change my two-factor app". Scan the QR code with your new app, then enter a code from your new app and a code from your old app to confirm. Once confirmed, only your new app will be accepted.

Keep your old phone until the change is confirmed!

You no longer have your old phone​

If your app could not restore your Gladys entry, you can't generate 2FA codes anymore. You can still replace your app yourself, with your recovery codes:

  1. Log in on plus.gladysassistant.com with a recovery code (see Using a recovery code below).
  2. Go to Settings > Security, card "Your two-factor app", and click on "Change my two-factor app".
  3. Scan the QR code with your new app, and enter the code it displays.
  4. For the code of the current app, click on "Lost your current app? Use a recovery code instead.", then enter another one of your recovery codes.
  5. Click on "Replace my two-factor app".

So you need two recovery codes: one to log in, one to replace the app. The second one is only used up if the replacement succeeds: if the code of your new app is refused, you can try again without losing a code. Your other recovery codes stay valid, but remember to generate a new set once your new app is set up.

No recovery code left, or only one? See I have no recovery codes left.

Using a recovery code​

Recovery codes are single-use codes that let you log in when you don't have access to your authenticator app anymore. They are displayed only once: when you enable 2FA, and each time you generate a new set.

To use one, on the 2FA code screen, look for "Lost access to your two-factor app?" and click on "Use a recovery code", and enter one of your codes. Each code can only be used once: cross it out once used.

Generate recovery codes (before you need them!)​

If you never saved your recovery codes, or if you used most of them, generate a new set now, while you still have access to your authenticator app:

  1. Log in on plus.gladysassistant.com.
  2. Go to Settings > Security.
  3. Click on "Generate recovery codes", and enter a code from your 2FA app to confirm.
  4. Save these codes somewhere safe, outside of your phone: a password manager, or printed on paper. They won't be displayed again.

Generating a new set immediately invalidates your previous recovery codes.

I have no recovery codes left​

You lost both your authenticator app and your recovery codes? Since Gladys 5.3.1, you can get back into your account without writing to support. Pick the solution that matches your situation:

Generate new codes from your Gladys​

Your Gladys, physically at your home, is already a trusted device of your Gladys Plus account: it can stand in for your 2FA app, just long enough to give you a new set of recovery codes.

  1. Open your Gladys locally, from your home network, with its local address (for example its IP address). This action is not available from plus.gladysassistant.com: the whole point is to be at home.
  2. Log in with an admin account of your Gladys.
  3. Go to Settings > Users. Under your user, in the "Remote access · Gladys Plus" section, click on "Recovery codes".
  4. Enter your Gladys password (the one of your local instance, not your Gladys Plus password), then click on "Generate".
  5. Gladys displays 10 new recovery codes, only once: copy or download them, and save them somewhere safe. Nothing is kept on your Gladys.

Your previous recovery codes stop working right away, and Gladys Plus notifies you by email. Your Gladys Plus password is still needed to log in: these codes only stand in for your 2FA app. Then log in on plus.gladysassistant.com with one of these codes, and replace your 2FA app as explained in You no longer have your old phone.

Good to know:

  • The "Recovery codes" button only shows up if your Gladys already knows your Gladys Plus account, that is if the fingerprints of your encryption keys are displayed under your user.
  • You are not an admin of your Gladys? Ask the person who manages Gladys at your home: they can generate these codes for you, by entering their own Gladys password, and then pass them on to you.

Have another admin reset your 2FA​

If your Gladys Plus account has another admin who still has access to their 2FA app, they can reset your two-factor authentication from Gladys Plus:

  1. They log in on plus.gladysassistant.com and go to Settings > Users.
  2. Under your user, in the "Remote access · Gladys Plus" section, they click on "Reset two-factor authentication".
  3. They enter the code of their own 2FA app, then click on "Reset".

You are notified by email. Then log in with your password: Gladys Plus immediately asks you to set up a new authenticator app, then to save new recovery codes. Your encryption keys and your access to your Gladys don't change.

An admin can't reset their own two-factor authentication this way.

Reset your 2FA by email, when no Gladys is connected​

If no Gladys is connected to your Gladys Plus account (never installed, broken or lost hardware, long power cut...), you can reset your two-factor authentication by email, right away:

  1. On plus.gladysassistant.com, log in with your email address and your password.
  2. On the 2FA code screen, under "Lost access to your two-factor app?", click on "No Gladys connected? Reset your two-factor authentication by email."
  3. Open the email you receive, and click on the link. It only works once and expires after one hour (you can only request one per minute: remember to check your spam folder).
  4. On the page that opens, click on "Reset my two-factor authentication".
  5. Log in with your password: Gladys Plus asks you to set up a new authenticator app, then to save new recovery codes.

Your old app and your old recovery codes don't work anymore, and you are notified by email once the reset is done. Your encryption keys don't change.

You also forgot your password? Start with "I forgot my password": the reset password page, opened from the email you receive, offers the same link under the two-factor fields. Once your 2FA is reset, come back to this page to choose your new password: the reset password link stays valid for two hours.

Your Gladys is connected? The reset by email is then refused, on purpose: your Gladys, at home, is the last resort of your account, and an admin of your Gladys can generate new recovery codes instead. This check is done when you request the link and when you click on it: if your Gladys comes back online in between, the link is refused, but it stays usable as long as no Gladys is connected.

After a password or 2FA reset​

Resetting your two-factor authentication (by an admin or by email) changes neither your encryption keys nor your access to your Gladys: once your new app is set up, everything works as before.

Resetting your Gladys Plus password ("I forgot my password"), on the other hand, generates new encryption keys. Gladys Plus is end-to-end encrypted, and your Gladys only accepts the keys you authorized at your home: your remote access is therefore automatically revoked, for security reasons. This is expected, nothing is broken: on plus.gladysassistant.com, a page explains what to do.

To get your access back, an admin of your Gladys opens your instance locally and goes to Settings > Users. Under your user, in the "Remote access · Gladys Plus" section, they check that the fingerprints of your new keys match the ones displayed on your Gladys Plus page, then turn on the "Authorized" switch.

Contact us​

None of the solutions above worked? Write to us at hello@gladysassistant.com from the email address of your Gladys Plus account, so that we can identify your account, and tell us what you already tried.

You can also ask your question on the community forum.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂