Two-factor authentication

Two-factor authentication protects accounts even when a password is stolen or guessed: after their password, the user must present a second factor.

It applies to accounts whose password is verified by Cyberwatch itself, that is to say local accounts and LDAP accounts. Accounts that sign in through SAML or OpenID Connect rely on their identity provider, which then manages the second factor itself.

Available second factors

Second factorHow it works
Authenticator appAn app such as Google Authenticator or Microsoft Authenticator displays a 6-digit code, renewed every 30 seconds (TOTP).
PasskeyThe phone, the computer, the password manager or a FIDO2 security key confirms the identity of the user by fingerprint, face or PIN (passkey, WebAuthn).
Recovery codesTen single-use codes, generated with the first second factor, allow signing in if the phone or the key is lost.

A user can set up one authenticator app and several passkeys.

Passkey prerequisites

A passkey is bound to the address of Cyberwatch. To use passkeys:

  • Cyberwatch must be opened through a domain name over HTTPS, at the address configured for the node in Administration > Nodes. Passkeys do not work when Cyberwatch is opened through an IP address;
  • the TLS certificate of Cyberwatch must be trusted by the browser;
  • the browser must be recent: Chrome or Edge 129, Firefox 119, Safari 18.4 or later versions.

When these conditions are not met, the authenticator app remains available.

Changing the address of the node makes the passkeys registered for the old address unusable. Cyberwatch warns the administrator who changes the address. The users concerned then sign in with their authenticator app or a recovery code, and register a new passkey.

Set up your second factor

  1. Open your profile from the menu at the top right of the interface
  2. In the “Two-factor authentication” box, click on “Manage”

Adding, replacing or removing a second factor, or generating new recovery codes, requires confirming your password. This confirmation remains valid for 10 minutes.

Authenticator app

  1. In the “Authenticator app” box, click on “Set up”
  2. Scan the QR code with the app, or enter the key displayed under the QR code
  3. Enter the 6-digit code displayed by the app, then click on “Enable”

The codes depend on the time. If a code is rejected, compare the time of the phone with the server time displayed under the form: a difference of more than 30 seconds prevents the verification.

Passkeys

  1. In the “Passkeys” box, click on “Add a passkey”
  2. Give the key a name, for example “Phone” or “Security key”
  3. Click on “Create the passkey”, then follow the instructions of the browser

Each key can then be renamed or removed from the same page.

Recovery codes

Recovery codes are displayed only once, when the first second factor is set up. They must be kept in a safe place, for example in a password manager: the “Copy to clipboard” and “Download” buttons make it easier to save them.

Each code can only be used once. The “Recovery codes” box indicates the number of remaining codes, and the “Generate new codes” button replaces all existing codes.

Notifications

An email notifies the user when a second factor is added or removed, when their recovery codes are regenerated, when a recovery code is used or when an administrator resets their second factors. Sending it requires a configured SMTP server.

Sign in

After entering the password, Cyberwatch asks for the second factor:

  • click on “Use a passkey”, if a key has been registered;
  • or enter the code of the authenticator app;
  • or enter one of the recovery codes.

After five rejected codes or keys within 15 minutes, entering the second factor is blocked for up to 15 minutes for this account.

Passwordless sign-in

A local user who has registered a passkey can sign in without entering a login or a password, with the “Sign in with a passkey” button on the sign-in page. The browser can also offer the key directly in the login field.

The passkey then verifies the identity of the user by fingerprint, face or PIN, which counts as two-factor authentication.

This sign-in is not offered to LDAP accounts, whose password must be verified by the directory at each sign-in.

Enforce two-factor authentication

By default, two-factor authentication is optional. To enforce it:

  1. Go to the Administration > Authentication provider > Global configuration menu
  2. In the “Two-factor authentication” section, choose the second factor:
    • “Optional”: each user chooses whether to set up a second factor;
    • “Required for administrators”: the users with the Administrator role must set one up;
    • “Required for all users”: all local and LDAP accounts must set one up.
  3. Click on “Save”

An affected user who does not have a second factor yet must set one up at their next sign-in, before accessing Cyberwatch. Sessions already open are not closed.

When two-factor authentication is enforced, a user cannot remove their last second factor. They can however replace it.

Before enforcing two-factor authentication, it is recommended that the administrator sets up their own second factor. A warning reminds them of this in the global configuration.

Monitor adoption

The “MFA” column of the users list indicates who has set up a second factor. It remains empty for SAML and OpenID Connect accounts as well as for password-less accounts.

The mfa_enabled attribute of the /api/v3/users API provides the same information.

Reset the second factors of a user

When a user has lost their phone, their passkeys and their recovery codes, an administrator can reset their second factors:

  1. Go to the Administration > Users menu
  2. Open the user’s page
  3. In the “Two-factor authentication” box, click on “Reset”, then confirm

The user then signs in with their password alone, and sets up a new second factor, during their sign-in if two-factor authentication is enforced. The reset is recorded in the activity log and the user is notified by email.

An administrator cannot reset their own second factors from the interface.