Two-Factor Authentication (2FA)
Two-factor authentication asks users for a second proof of identity after their password: a code from an authenticator app, a code sent by email or text message, or a Duo push. Even if a password is stolen, the account cannot be used without the second factor.
This article is for administrators. For the user's view, see Signing In with Two-Factor Authentication.
DashboardFox Cloud: your site starts with mode Optional and the Authenticator app, Email code and Text message methods switched on; text messages are sent from our number. You can change the mode, including to Required. Duo and your own text-message provider need the Enterprise plan. See Security Settings on DashboardFox Cloud.
Default behavior
On a self-hosted server two-factor mode is off by default and no method is switched on. No user is prompted and the two-factor section is hidden from user profiles.
Methods
Method | How the user gets the code | Needs | Works offline |
|---|---|---|---|
Authenticator app | Google Authenticator, Microsoft Authenticator, Authy, 1Password, or any app that scans a QR code | Nothing | Yes |
Email code | 6-digit code emailed to the user's address | Outgoing email (SMTP) | No |
Text message (SMS) | 6-digit code sent to the user's phone | A text-message provider — see Setting Up Text-Message (SMS) Codes | No |
Duo | Duo Mobile push or passcode | A Duo account and the Duo fields on this page | No |
Codes expire after 10 minutes. The authenticator app has no external dependency and is the most reliable; we recommend offering it to everyone.
Users may set up more than one method — for example an authenticator app as their primary method and email code as a fallback. At sign-in they can choose Try another way to use any method they have enrolled.
Modes
Mode | Behavior |
|---|---|
Off | No prompts. |
Optional | Users may turn on 2FA from My Profile → Two-factor authentication. Users who have enrolled are prompted at every sign-in. An administrator can ask a specific user to set it up (see Managing User Accounts). |
Required | Every user who signs in with a password must enroll. Users who have not enrolled are stopped at sign-in and must set up a method before reaching the application. Users cannot turn 2FA off or remove their last method themselves. |
Users who sign in through SSO, Windows authentication, or an external identity provider are not prompted in any mode; their identity provider is expected to enforce 2FA. Service accounts are never prompted either, even in Required mode — see Service Accounts for Integrations and Embedding.
Before switching to Required
Required mode stops every password user who has not enrolled, including accounts that are not people:
Accounts used by integrations, embedded dashboards, scheduled exports or Server Sync sign in automatically and cannot answer a code. Mark them as service accounts first.
Make sure at least two administrators have enrolled and saved their backup codes.
Make sure outgoing email works if you offer the Email code method.
Turning two-factor authentication on
Go to Settings → Server Settings → Security Settings and scroll to Two-Factor Authentication.
Set Mode to Optional or Required.
Under Allowed methods, switch on at least one method. Switching on Text message (SMS) reveals the provider settings; switching on Duo reveals the Duo fields. If outgoing email is not configured, an Email is not set up warning appears under Email code.
Click Save (one Save button covers the whole page, including the text-message provider).
The page refuses to save a mode other than Off with no method switched on, or the Text message method without a provider selected.
Recommended rollout: Start with Optional. Enroll yourself and other administrators, confirm codes arrive, and keep your backup codes. Then switch to Required. In Required mode every user who has not enrolled is prompted at their next sign-in.
What users see
First setup (Required mode, or after choosing to enroll, or when an administrator asked them to):
After entering their password, the user sees the setup screen with the allowed methods.
Authenticator app: a QR code and a text key to scan or type into their app, then a field for the first code.
Email or text message: a code is sent; the screen says where it went and offers Resend. For text message the user enters their mobile number first.
Ten backup codes are shown once, with a download button. Each works once in place of a code.
Every later sign-in:
Password, then the code prompt for their primary method. Email and text codes are sent automatically; there is a Resend link.
Try another way lists the user's other enrolled methods.
Use a backup code switches the field to accept a backup code.
Remember this device for 30 days skips the prompt on that browser until the period ends or the device is revoked.
If a user's session expires while they are working, the sign-in window that appears runs the same two-factor step inline; Duo users are taken to the sign-in page.
Managing users
Reset 2FA for a user (lost phone, new number, locked out of their authenticator):
Go to Settings → Security → Users and open the user.
Under Additional Options the Two-factor line lists their methods. Click Reset 2FA and confirm.
This removes every method, the backup codes and remembered devices, and ends the user's current session. In Required mode the user enrolls again at their next sign-in. In Optional mode 2FA is off for the user until they turn it on again. The reset is recorded in the Audit Log.
Ask a user to set it up. In the user editor, set Two Factor Authentication to Ask to set up 2FA at next sign-in and save. At their next sign-in the user sees the setup screen; in Optional mode they may choose Skip for now and will be asked again each time until they enroll.
Duo is the only method an administrator assigns directly (set the dropdown to Duo). Authenticator app, email and text message are always set up by the user.
Backup codes and remembered devices
Backup codes are created the first time a user enrolls. Users can regenerate them from their profile; the old set stops working.
Users can forget all remembered devices from their profile. Reset 2FA by an administrator also forgets them.
A remembered device is tied to the browser. Clearing browser data or using a different browser prompts for a code again.
Troubleshooting
Authenticator codes are always rejected. The phone's clock is wrong. Authenticator codes depend on the time; have the user enable automatic time on the phone. Check the server's clock as well.
Email codes do not arrive. Check Settings → Scheduler → Mail Settings and the user's email address in their profile. Codes expire after 10 minutes; ask the user to click Resend.
Text codes do not arrive. Use Send test SMS on the Security Settings page to confirm the provider works. Check the user's mobile number includes the country code.
A user is stuck at the setup screen. In Required mode they must finish enrolling. If they cannot (no phone, no email access), reset their 2FA and temporarily set the mode to Optional, or set them up with an authenticator app on a desktop app such as 1Password or Authy.
An integration, embedded dashboard or Server Sync stopped working after switching to Required. The account it signs in with now receives a two-factor prompt it cannot answer. Mark that account as a service account, or sign those users in through SSO or an external identity provider.
Duo users. Duo works as before. If Mode is Off, Duo prompts are also off; set it to Optional or Required and keep the Duo switch on.
Turning two-factor authentication off
Set Mode to Off and save. Users are no longer prompted. Their enrollments are kept, so turning the mode back on restores them.
Frequently asked questions
Can I require 2FA for some users only? Use Optional mode and set Ask to set up 2FA at next sign-in on those users. They can skip, but are asked every time until they enroll.
Can users choose their own method? Yes, any method in Allowed methods, and more than one. They choose which is primary.
Where are secrets stored? On your server, encrypted. Codes sent by email or text are never stored in readable form.
Is this recorded? Yes. Enrollment, each prompt, each success or failure, backup code use, remembered devices, administrator resets and service-account bypasses appear in Settings → Audit Log.