Two-factor sign-in

Two-factor sign-in is on from the first start. A platform administrator who signs in with a local password, and every break-glass account, gives a six-digit code from an authenticator app as well. People who sign in through Microsoft Entra ID or another OpenID Connect provider use the provider’s own second factor.

Enrol an authenticator app#

The first sign-in that needs a code enrols the app. The admin UI shows the setup code for the authenticator app, which then gives a standard time-based one-time password of 6 digits every 30 seconds, and the first valid code confirms the enrolment. The first local admin does this when they open the set-password link that init printed.

The admin UI then shows ten recovery codes once. Keep them apart from the platform, as you keep the master key. Each code signs the person in once when the authenticator app is lost.

Who gives a code#

While two-factor sign-in is required, which is the default:

• A platform administrator who signs in with a local password gives a code at every sign-in.
• A break-glass account always gives a code, whatever the setting says.
• A person who has enrolled an app is asked for its code even while the rule is off, so turning the rule off removes no factor from anyone who has one.
• A federated sign-in relies on the identity provider’s own second factor.

A wrong code counts toward the account’s lockout like a wrong password: five wrong answers within 15 minutes lock the account for 15 minutes.

Turn it off for a sandbox#

An installation where administrators can’t use an authenticator app, such as a local sandbox, turns the rule off:

$ weikio settings set --two-factor-required=false --reason "local sandbox without authenticator apps"

While it’s off, weikio problems lists the warning two-factor-off for platform administrators, and Settings › Installation shows Two-factor sign-in as Off in the warning colour with how to turn it on again. --two-factor-required=true turns it on. The change is audited with its reason, like every change of the installation’s settings.

The admin UI’s Edit installation settings sets the same choice, Required or Off, with each choice’s explanation and a warning before a save that turns it off. A settings document that leaves the field out turns the requirement back on, so an old export applied with weikio apply -f never switches it off by accident.

Reset a lost authenticator#

When a person loses their phone and their recovery codes, another platform administrator clears their authenticator app:

$ weikio user reset-totp anna.virtanen@example.com

The person enrols a new app at their next sign-in. A platform administrator can’t clear their own, so keep at least two platform administrators.