Two-factor authentication
Two-factor authentication asks for something the person has — a code from an app on their phone, or a code sent to their mailbox — as well as the password they know. This page explains how to switch it on for the portal and the console, and what your users see.
Why use two-factor authentication
Passwords get reused, guessed and leaked. With two-factor authentication switched on, a stolen password on its own is not enough to sign in: the attacker also needs the person's phone or mailbox. For a portal published on the internet, and above all for the admin console, it is the single most effective protection you can add.
The two methods
| Method | How it works | Good for |
|---|---|---|
| Authenticator App | The person scans a code into an authenticator app (Microsoft Authenticator, Google Authenticator and similar) once. From then on the app shows a short code that changes every few seconds, which they type at sign-in. It works with no network connection on the phone. | Administrators, and anyone with a smartphone. The stronger of the two. |
| Email one-time code | After the password, DartRelay emails a six-digit code to the address on the person's account. They type it in to finish signing in. | People without a smartphone. It needs working email delivery and an email address on each account. |
Before you begin
- For email codes, set up email delivery first and send yourself a test. See Email delivery and templates.
- For email codes, make sure every account that will use them has an email address.
- Check that the server's clock is correct. Authenticator codes depend on the time on the server and on the phone agreeing.
- The settings need the Security permission. See Administrator roles and permissions.
Switching two-factor authentication on
The portal and the console are configured separately, so you can, for example, require it on the console while leaving it optional on the portal.
- Open the Security page. In the console, go to Authentication → Security. The two-factor settings are in the first card.
- Choose the mode for the admin console. Modes run from disabled (no second step) to mandatory (everyone must use it).
- Choose the mode for the portal.
- Choose the methods to offer. Tick Authenticator App to offer app codes. Switch on email codes to offer those.
- Set the grace period. When two-factor authentication is mandatory, the grace period is the number of days people have to set it up before they can no longer sign in without it. The console and the portal each have their own.
- Click Save under the two-factor card. The card saves on its own, separately from the other cards on the page.
Saving the Security page sends the security-settings message to the Admin Notification Emails list, so other administrators know the setting changed.
Make it mandatory on the console first. Administrators can change everything, so their accounts are the most valuable to an attacker, and they are the easiest group to help through setting it up.
Example: a sensible starting point
A practice with 40 staff publishes its clinical system to home workers. The administrator sets the console to mandatory with Authenticator App only, and a short grace period for the two IT staff. For the portal they offer both methods with a longer grace period, so staff without a work phone can use email codes, and they announce the change on the sign-in page with an Announcement a week ahead.
How people set it up
When a method is offered on the portal, the person's profile page shows a card for it. When two-factor authentication is switched off, those cards are not shown at all.
- Open the profile. In the portal, open the account menu and choose the profile page.
- Set up the authenticator app. In the authenticator card, scan the code shown on screen with the app and follow the prompts on the page.
- Keep the recovery codes. DartRelay gives a set of one-time recovery codes. Each can be used once in place of an app code, for example if the phone is lost. Store them somewhere safe and separate from the phone.
People manage their authenticator devices and recovery codes from the same profile page. See Signing in and out for the end-user view.
Recovery codes are a limited set. Someone who has used them all and lost their phone needs an administrator's help to get back in.
What signing in looks like
- The person types their username and password as usual.
- DartRelay shows the next step on the same branded sign-in page — the theme's logo, background and colours stay in place, and the code form takes the place of the sign-in form.
- For an app code, they type the code the app is showing (or a recovery code). For an email code, the page says where the code was sent, with most of the address hidden, for example
jo****@example.com. - Once the code is accepted, they arrive at My Resources.
Email codes in detail
- Resend. The code page has a Resend button. To prevent message floods, a new code is sent at most once a minute; reloading the page within that minute does not send another.
- Codes expire. A code is valid for a limited time. An expired code is refused; press Resend for a new one.
- Wrong codes count. Every wrong code counts towards the failed-attempt lockout, exactly as a wrong password does. See The failed-attempt lockout.
- When a code cannot be sent, the page says so and why, rather than claiming a code is on its way. The usual reasons are an account with no email address, email delivery not working, or the message switched off.
- The wording is yours. The message is the Email one-time code template under Email → Templates. You can reword and translate it.
Switching the Email one-time code template off means no code is sent at all, so nobody can complete an email second step. To stop using email codes, switch the method off on Authentication → Security instead. The template editor repeats this warning beside the switch.
Email codes and self-service password reset links go to the same mailbox. If you use both, someone with access to a person's mailbox could reset the password and receive the code. For stronger protection, prefer the authenticator app. See Self-service password reset.
After a forced password change
When someone has to change an expired password, the change screen sends them back to sign in normally afterwards. The second step is asked for then, so a password change never skips two-factor authentication.
If something goes wrong
Authenticator codes are always refused
The clock on the phone or on the DartRelay server is probably wrong. Set both to synchronise their time automatically and try again.
No email code arrives
Check that the account has an email address, that the Email one-time code template is switched on under Email → Templates, and that email delivery works by sending a test from the template editor. Check the recipient's junk folder. If the page says a code could not be sent, its reason tells you which of these to look at.
Someone is locked out after mistyping codes
Wrong codes count towards the lockout for their network address. They can try again once the lockout duration on System → Settings has passed. A correct sign-in then clears the count.
The two-factor cards are missing from the profile page
They appear only when a method is offered for the portal on Authentication → Security.
Related pages
Sign-in protection
Lockouts, captcha and network address lists.
Email delivery and templates
Set up the mail server that carries email codes.
Password policy and self-service reset
Expiry, forced changes and reset links.
Signing in and out
What your users see at the sign-in page.