Skip to main content

Two-step sign-in

Two-step sign-in (MFA) asks for a six-digit code from an authenticator app after the password. Any standard authenticator app works: Microsoft Authenticator, Google Authenticator, 1Password and the like.

It applies to the password sign-ins: Active Directory, the local administrator, and demo accounts. People who sign in with Entra ID are never asked, because Entra does its own MFA through conditional access.

Who must use it​

An administrator chooses under Settings > Sign-in, in the Two-step sign-in (MFA) section:

ChoiceEffect
Not requiredNobody has to. Anyone may still turn it on for themselves under My account. This is the default
Required for administratorsEveryone who is an administrator must use it, including the local administrator
Required for everyoneEveryone who signs in with a password must use it

The choice is saved as soon as you click it. People who must use it and have not set it up yet do so at their next sign-in. People already signed in stay signed in until their session ends.

Whatever the choice, anyone who has set it up is asked for a code at every sign-in.

Setting it up at sign-in​

Someone who must use two-step sign-in and has not set it up sees this after typing their password:

  1. Set up two-step sign-in. A QR code to scan with the authenticator app. If they cannot scan it, Cannot scan it? shows a key to type into the app instead.
  2. They type the 6-digit code the app shows and press Turn on and sign in.
  3. They are shown ten recovery codes. Each one signs them in once if they lose their phone. Copy the codes, keep them somewhere safe away from the phone, then press I have saved them; continue.

The codes are shown once only. Delegaris keeps only a fingerprint (hash) of each.

People can also set it up for themselves at any time under My account, whether or not it is required.

Signing in with a code​

After the password, the page asks: "Type the 6-digit code from your authenticator app." The person types it and presses Sign in.

  • A code from just before or just after the current one also counts, for phones whose clock is slightly out.
  • A code works once. The same code cannot be used again, so someone who sees it over a shoulder cannot reuse it.
  • Nothing is signed in until the second step is through. The password alone gives no session.
  • The second step must be finished within 5 minutes of the password. After that the page says "That took too long. Sign in again."

Lost phone​

On the code step, Lost your phone? Use a recovery code switches to a box for a recovery code. Each recovery code works once. The person should then set up the app again on their new phone under My account, and make new recovery codes.

Wrong codes are throttled​

After 5 wrong codes at sign-in within 5 minutes for one person, further codes are refused with "Too many wrong codes. Try again in a few minutes." The same applies to codes typed under My account. These use the same limits as wrong passwords (LOGIN_MAX_FAILURES, LOGIN_FAILURE_WINDOW_SECONDS).

A wrong code says "That code is not right, or has already been used."

Seeing who has set it up​

The Two-step sign-in (MFA) section under Settings > Sign-in lists everyone who has set it up:

ColumnWhat it shows
Set up byThe person's name and sign-in name
SinceWhen they set it up
Recovery codes leftHow many unused recovery codes they have

If nobody has set it up, it says "Nobody has set it up yet."

Resetting someone's two-step sign-in​

For someone who has lost their phone and their recovery codes:

  1. Open Settings > Sign-in and find them in the Two-step sign-in (MFA) list.
  2. Press Reset (lost phone).

Their app and recovery codes stop working. At their next sign-in they set it up again if it is required, or sign in with their password alone if it is not.

Make sure it really is them asking before you reset it.

Resetting the local administrator from the host​

If the local administrator is the one locked out, and there is no other administrator to press Reset (lost phone), reset it from the host where Delegaris runs. With Docker, from the folder with your docker-compose.yml:

docker compose exec delegaris python -m app.mfa reset admin

With the Linux package:

sudo delegaris mfa reset admin

It answers "MFA reset for admin: they set it up again at their next sign-in." The same command works for any sign-in name: python -m app.mfa reset <username> in the container, or sudo delegaris mfa reset <username>.

Activity​

Every step is recorded in the activity log: a password accepted with a code still to come, sign-ins "with MFA" (saying whether a code or a recovery code was used), set-up, new recovery codes, turning it off, resets, and changes to the policy.

Next steps​