Two-factor authentication settings¶
Site-level configuration for two-factor authentication, set in Site
Settings → Two-Factor Authentication and stored in siteConfig.mfa and
siteConfig.sms.
How values are read¶
Every field is optional. A missing or unreadable value falls back to the
default in the tables below, so a partial block is valid — {"mfa": {"enabled":
true}} is enough to switch the feature on with everything else at its default.
The master switch defaults to off. While it is off, sign-in is unchanged, the section is hidden from everyone's profile, and the management endpoints report the feature as unavailable.
Values are coerced rather than rejected: the settings page writes numbers as
strings and role lists as comma-separated text, and both are accepted. A value
that cannot be read at all reverts to its default rather than erroring — so a
mistyped enabled leaves the feature off, never on.
Two-factor authentication fields¶
| Field | Default | Meaning |
|---|---|---|
enabled |
false |
Master switch. Nothing happens for the site until this is true |
methods |
["totp","email","sms"] |
Which factors are offered. sms is dropped automatically unless a gateway is configured |
maxInterval |
10080 |
Longest gap a user may choose between challenges, in minutes (7 days) |
defaultInterval |
0 |
Gap a user starts on when they first enrol. 0 = every sign-in |
issuer |
site name | Name shown in the authenticator app and in code emails |
codeLength |
6 |
Digits in a texted or emailed code |
codeTTL |
10 |
Minutes a texted or emailed code stays valid |
ticketTTL |
10 |
Minutes a part-completed sign-in stays open |
maxAttempts |
5 |
Wrong codes before the attempt is abandoned |
resendCooldown |
30 |
Seconds before another code can be requested |
recoveryCodeCount |
10 |
Recovery codes issued per set |
enforceForRoles |
[] |
Roles for which 2FA is compulsory. Empty means opt-in only |
Interval choices offered to users are every sign-in (0), 12 hours (720), daily
(1440), weekly (10080) and monthly (43200), filtered to those at or below
maxInterval. A user submitting anything else is clamped to the site default
rather than rejected.
SMS gateway fields¶
Stored in siteConfig.sms. Only needed if methods includes sms.
| Field | Default | Meaning |
|---|---|---|
driver |
log |
log, twilio, or sns |
senderID |
eBiz |
Name shown as the sender. Ignored by carriers in some countries |
defaultCountryCode |
44 |
Applied to numbers entered in local trunk form, e.g. 07700 900123 |
twilio.from |
— | Sending number, required for the Twilio driver |
sns.region |
eu-west-1 |
AWS region for the SNS driver |
With driver left at log, codes are written to the application log and no
text is sent. The gateway counts as unconfigured, so sms is removed from the
offered methods and nobody can enrol into a factor they will never receive.
SNS takes no credentials. It authenticates with the EC2 instance role
through the AWS SDK's default provider chain, and the role needs sns:Publish.
Never set AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY on these boxes: static
keys take precedence over the instance role and break every other AWS client in
the application.
Role enforcement¶
Naming a role in enforceForRoles makes 2FA compulsory for anyone holding it.
Those users are made to enrol at their next sign-in before they get any access,
and cannot turn it off afterwards.
Enforcement is inert while enabled is false, so it cannot be armed by
accident ahead of the switch.
What this is not¶
- Not the suspicious activity monitor. That watches behaviour after sign-in and alerts administrators; this controls getting in at all. See security settings.
- Not per-user configuration. Methods, intervals and recovery codes belong to each person and are managed from their own profile. This page is only the site-wide policy that bounds those choices.
- Not retrospective. Raising
maxIntervaldoes not lengthen anyone's existing setting; lowering it pulls every user above the new cap down to it.