Setting up Two-Factor Authentication

Owned by Erin Quinn
Last updated: Dec 11, 2024 by Aashima Khanduja
5 min read

Some project spaces require users to login using two factor authentication (2FA). This is an extra security step that requires you to input a token from generated by your phone (via call, SMS, or an authenticator app) before you can complete your login to CommCare. If you need to troubleshoot 2FA, check out this page: Troubleshooting Two Factor Authentication Issues.

Initial 2FA Set Up (First Login)

When a web user or web apps user first logs in, they will be prompted to set up their 2FA as seen below. To begin, click "Enable Two-Factor Authentication": 

There are three methods you can use to generate a 2FA token— an authenticator application (an app that runs on Android or iOS smartphones), a phone call, or a text message. Select the method you would like to use for receiving tokens.

NOTE: Despite the setup wizard saying "Google" Authenticator, we allow for any authenticator application (such as MS Authenticator). We highly recommend using an Authenticator App as the preferred authentication method. The Phone call and Text message options are dependent on third party SMS carriers. In the event these carriers may be facing issues / delays, the user may not be able to receive tokens / may face a delay in receiving tokens, and this may result in the user being locked out of CommCare for the period these carriers are facing issues. In that case, the user may have to wait until the third party carrier issue is resolved. Thus, we recommend using an Authenticator for any user wanting to set up Two Factor Authentication on CommCare HQ, as this is a more reliable method, and avoids the dependency on third party carriers to receive tokens via calls or SMS.

Using An Authenticator Application 

If using an Authenticator application, you’ll need to first download the Authenticator app from the PlayStore or App Store. Once you install it, you’ll need to confirm your account, and add it using the QR code displayed in your setup wizard.

Click scan barcode, and then scan the QR code CommCare has generated for you. The Authenticator will produce a token that you can put into the Token box, and proceed. Note that tokens in Authenticators change frequently, so you need to type this in a timely manner.

Using Phone or SMS Options 

These methods are highly discouraged, as they're dependent on third party SMS carriers, and may result in a user being locked out if the third party carriers are facing any issues.

If you select phone or SMS, you’ll be promoted to put in your phone number, including + and the country code.

Once you’ve entered your phone number, you will receive a phone call or SMS with your token.

Generating Backup Tokens

You can also generate backup tokens to use whenever you're unable to generate a fresh token (e.g. you're not near your phone, or you're out of country using a different SIM card). It's always good to keep these on hand for situations where you think you might not be able to access your normal 2FA method.

To generate backup tokens:

  1. Go to the settings widget at the upper right hand corner, that looks like a gear icon 

  2. Select "My Account Settings"

  3. Click on Two Factor Authentication

  4. Click on "Show Codes" under the heading Backup Tokens

NOTE:

  • Backup tokens may only be used once. If you've used all your tokens, please re-generate them by following the method above

  • Backup tokens do not expire, but if you generate new tokens, the previous tokens are no longer valid.

Subsequent Logins

Every time you sign into CommCare HQ you will be asked to enter a token. Keep your phone nearby so you can easily get the token from your Authenticator app, the phone call, or SMS that CommCare sends you.

If you are using an Authenticator app for two factor authentication then you will have a limited time period to enter the code displayed otherwise a new randomly generated code will be created and the timer will reset.  Please enter the code displayed by the Authenticator app before the 30 second timer expires, but if you miss the first 30 second window it will still be valid for an additional 30 seconds.

For SMS codes, once received please enter them within 2 minutes for the code to be accepted, if you miss this window please resend a new valid code to be entered.

Change your Authentication Method

Users are able to change their authentication method. To do this, please: 

  1. Go to the settings widget at the upper right hand corner, that looks like a gear icon

  2. Select "My Account Settings"

  3. Click on Two Factor Authentication

  4. Select "Re-Set Two Factor Authentication" (see image above). This will make you go through the process of updating your two-factor process. Before doing this, please make sure you have tokens available to confirm your original two-factor, as the system will make you go through the process again.

Note: Users SHOULD NOT reset their 2FA themselves unless they have access to their backup token. If users lose access to their token, they MUST contact support for assistance with resetting 2FA.