Troubleshooting Two Factor Authentication Issues

This page outlines common scenarios to help unblock a user who may be facing Two Factor Authentication (2FA) issues. 

Using the Correct Authenticator App

We have found that users may have more than one authenticator app on their device at any given time. If this is the case, a user may mistakenly use the Google Authenticator app (for example) instead of the MS Authenticator app (or vice versa). Be sure to recommend users to use the same authenticator app used when originally setting up 2FA. 

Checking for Carrier Delays

If you are using SMS or Call to retrieve a token, you are subject to any delays the carrier may have. For instance, if your local telecom network is experiencing significant delays beyond 30 seconds for SMS or Calling, your token may be expired by the time you enter it into CommCare HQ. 

If you are finding that your tokens are not immediately sent via SMS or Call, first navigate to status.commcarehq.org to see if there is any issues on the CommCare HQ end. If you do not see any issues listed on that page, it is most likely a carrier issue and you need to wait until it is resolved.

Troubleshooting Google Authenticator via Time Correction

If CommCareHQ isn't accepting you 2FA code from the Google Authenticator app, you may need to have the Authenticator app sync down a"time correction".

To apply a time correction specifically for the Google Authenticator app, from the main screen select:

Open

After syncing, the service will attempt to apply a time correction and will respond with a message about the state of the sync service. You should note down this message and take any necessary steps before retrying your codes

Note: It is also a good idea to make sure that your phone's date and time are set automatically from the network, but the Authenticator's time sync can differ from the device clock. You should make sure Authenticator is in sync even if your device's date and time are correct.

What happens if you lose your backup tokens?

In the event that a user loses access to their backup token, the user should contact CommCare HQ support for next steps.

What is the process of resetting a user's 2FA?

If you have exhausted all options, including backup tokens, and need to reset your 2FA or recover your account for any reason, please start by emailing support@dimagi.com. 

2FA is purpose-designed to add layers of security in order to safeguard sensitive information and malicious attempts at gaining unwarrented access to systems. As such, Dimagi takes any action such as resetting or turning off 2FA very seriously. We have a multi-layer verification approach which may take days to weeks to properly verify a user's identity. We will prioritize the security of your account over the ease of access recovery. If verification cannot be established, Dimagi will not reset a user's 2FA setup.