Requires Powercode build 26.10.05 or later.
Two-factor authentication (2FA) adds a second step to signing in. After entering their password, a user also enters a 6-digit code. The code comes from an authenticator app on their phone, or Powercode sends it to them by email or text message. Someone who learns a password still can't get in without the code.
Powercode has separate 2FA settings for two groups of people:
For each group you choose a mode (who has to use 2FA) and a gateway (how codes are delivered). Everyone who sets up 2FA also gets ten single-use recovery codes to use if they lose their phone.
Upgrading from an earlier build? Everyone who uses 2FA has to set it up again at their next sign-in. Read After upgrading under How it works before you upgrade.
| What | Where |
|---|---|
| 2FA for the admin and installer portals | Config > System, in the Authentication section |
| 2FA for the customer portal | Accounts > Customer Portal, in the Two-factor authentication section |
| Your own 2FA (staff) | The user menu at the top of the page > Your Profile > Edit tab |
| Your own 2FA (customers) | The customer portal user menu > My Details |
| Resetting a staff user | Config > Users, then open the user. See Users. |
| Resetting a customer contact | Open the contact from the customer's account and click Edit next to Contact Details |
| Permission | Why it is needed |
|---|---|
| System (System → Configuration) | To change the staff 2FA settings on Config > System. |
| Customer Portal (System → Configuration) | To change the customer portal 2FA settings. |
| User (System → Users) | To show a user's setup code or reset their 2FA. |
| Contact (Customer → Information), with edit access | To show a contact's setup code or reset their 2FA. |
| Require two-factor authentication (Configuration → Admin Portal) | This one doesn't open anything. When the mode is Permission based, users in a group that has it must use 2FA. |
| Mode | What happens at sign-in | Can users turn 2FA off themselves? |
|---|---|---|
| Off | No 2FA. Nobody is asked for a code. | Not applicable |
| Optional | Users who have set up 2FA enter a code. Users who haven't see the setup screen at every sign-in, with a Skip for now button. | Yes, from their profile |
| Required | Everyone must use 2FA. Users who haven't set it up must finish setup before they get in. There is no Skip for now. | No |
| Permission based (staff only) | Users in a permission group with Require two-factor authentication are treated as Required. Everyone else is treated as Optional. | Only users without the permission |
The customer portal offers Off, Optional and Required. Contacts aren't in permission groups, so there is no permission-based mode for them.
Skip for now appears only when 2FA is optional for that user: the mode is Optional, or it's Permission based and the user doesn't have the permission. Skipping lets them in for that sign-in only. The setup screen comes back at their next sign-in until they finish setup.
Switching the mode to Off doesn't erase anyone's setup. If you turn 2FA back on later, users who had already set it up are asked for a code straight away.
The gateway decides how users get their codes.
| Gateway | How the user gets a code |
|---|---|
| Powercode emails a 6-digit code, with the subject "Authentication Code", to the email address on the user's record (for customers, the contact's email address). It goes out with your other outbound email, so it depends on your Mail Server Configuration. | |
| SMS | Powercode texts a 6-digit code to the user's phone number (for customers, the contact's main phone number). SMS is only listed when the Twilio integration is turned on. See Twilio. |
| GoogleAuthenticator (staff settings) or Google Authenticator (customer portal settings) | The user reads the 6-digit code from an authenticator app on their phone. Nothing is sent. |
When E-mail or SMS is selected, a 2FA Code Message field appears. It holds the text placed in front of the code in a text message. The default is Authentication Code:. The email uses a standard layout instead of this text.
If you switch the gateway to Google Authenticator, users who set up 2FA with E-mail or SMS don't have an authenticator app yet. They're sent to the setup screen at their next sign-in.
Only users with the User permission can reset someone else's 2FA. If only one active user has it, Powercode still saves your settings but shows this warning: "Only one active account can reset two-factor authentication. If that person loses both their authenticator and their recovery codes, restoring access will require direct database access. Consider granting user-edit permission to a second account."
In this build, if the Twilio integration is turned off, saving the Customer Portal page always sets the customer portal gateway to E-mail, even if you picked Google Authenticator.
Setting up (sometimes called enrolling) is what turns 2FA on for a person. Until they finish setup, Powercode never asks them for a code.
If Skip for now appears under Finish setup, you can skip setup for this sign-in. Cancel returns you to the sign-in page.
When the staff gateway is Google Authenticator, you can also set up 2FA without signing out:
When the customer portal gateway is Google Authenticator, a Two-factor authentication section on My Details shows a QR code and the key ("Or enter this key manually:"). The contact scans it, enters the code and clicks Finish setup, and their recovery codes are shown once.
When the gateway is Google Authenticator, you can show the QR code for someone who hasn't finished setup. This is handy if you're helping them in person.
The person scans the code into their app. When they next sign in, the setup screen shows that same code instead of a new one, so they only need to enter a code from their app and click Finish setup. Each time someone views a setup code, it's recorded in the System Event Log.
If you've lost your phone, click Use a recovery code, type one of your recovery codes in the Recovery code box and click Verify. Use your authenticator app switches back to the code boxes.
Recovery codes are your way back in if you lose the device with your authenticator app.
XXXXX-XXXXX, made of letters and numbers.Staff can manage their codes on Your Profile > Edit, in the Two-Factor Authentication section:
Customers only see their codes when they finish setup. The customer portal doesn't show how many are left and can't create new ones. If a contact runs out or loses them, reset their 2FA from the contact page.
When 2FA isn't required for you, the Two-Factor Authentication section on Your Profile > Edit has a Turn off two-factor authentication button. It removes your authenticator setup and your recovery codes. If the mode is Optional, the setup screen appears again at your next sign-in.
If 2FA is required for you, the section says "Your administrator requires two-factor authentication, so it cannot be turned off."
Customers get the same Turn off two-factor authentication button on My Details when the customer portal mode is Optional and the gateway is Google Authenticator.
Reset a person's 2FA when they've lost their phone and their recovery codes, or when they're locked out after too many wrong codes. A reset removes their authenticator setup and recovery codes and clears the failed-attempt count. If 2FA is still on, they set it up again at their next sign-in.
The reset buttons and Show setup code only appear when the gateway is Google Authenticator. Every reset is recorded in the System Event Log.
The installer portal uses the staff settings on Config > System: the same mode, the same gateway, and the same setup for each user. Setting up 2FA in either the admin portal or the installer portal covers both.
On the installer portal:
Before 26.10.05 the installer portal never asked for a code, even when 2FA was turned on. Staff who skipped setup in the admin portal will see the setup screen on the installer portal too.
If 2FA was turned on before you upgraded to 26.10.05:
Tell your staff and customers before you upgrade. To ease the change, set the mode to Optional for a while so people can skip setup until they're ready.
| Symptom | Likely cause |
|---|---|
| Invalid authentication code | The code was mistyped or has expired. Authenticator codes depend on the time, so check that the phone's clock is set automatically. On E-mail and SMS, use the newest code you were sent. |
| Invalid recovery code | The code was mistyped, has already been used, or belongs to an old set that was regenerated or reset. |
| Sent back to the sign-in page after entering codes | Ten wrong codes in one sign-in. Sign in again. |
| This user (username) has too many failed login attempts! (admin portal), Too many bad login attempts! (installer portal) or Too many failed authentication attempts. Please contact support. (customer portal) | The account hit the limit of 30 wrong 2FA codes. In the admin and installer portals, the same messages also appear after too many wrong passwords. Reset the person's 2FA. |
| Could not to send Authentication Code. or SMS failed | Powercode couldn't send the code. Check the outbound email settings or the Twilio integration, and the email address or phone number on the user or contact. |
| An email code never arrives | Check the email address on the user's record (or the contact's) and your Mail Server Configuration. |
| The setup screen appears at every sign-in | The mode is Optional (or Permission based without the permission) and the person keeps choosing Skip for now. |
| No Skip for now button | 2FA is required for this person: the mode is Required, or Permission based and they're in a group with Require two-factor authentication. |
| Two-factor authentication is required on your account. | Someone tried to skip setup when 2FA is required for them. |
| Two-factor authentication is not set up on your account. shows on every page | The user is signed in without having set up 2FA, for example through single sign-on. Click Set up two-factor authentication in the notice to set it up from your profile. |
| Too many attempts. Log out and back in to try again. | Ten wrong codes while setting up from a profile page. Sign out and back in. |
| No QR code on the profile page | The gateway isn't Google Authenticator, or you've already finished setup. |
| No reset button on the user or contact page | The gateway isn't Google Authenticator, or the person hasn't finished setup (you'll see Show setup code instead). |
| Everyone was asked to set up again after switching to Google Authenticator | Expected. People who set up with E-mail or SMS have no authenticator app yet. |
| The customer portal gateway keeps going back to E-mail | The Twilio integration is turned off. See Limitations. |