Two-step verification

With two-step verification, your password is not enough to sign in to the panel: you also need a 6-digit code that changes every 30 seconds in the authenticator app on your phone (Google Authenticator, Microsoft Authenticator, Aegis, 1Password or any other TOTP app). Someone who finds out the password still cannot get in.

It works for administrators, for customers and for the people in their teams: everyone turns it on for themselves, with their own phone.

Turning it on

1. Open My account (at the bottom of the menu, "Password and verification").
2. In Two-step verification press Turn on and enter your password.
3. Scan the QR code with the phone app. If you can't, type the key shown below it by hand; on the phone you can also tap Open in the app.
4. Enter the 6-digit code the app shows and press Confirm and turn on.
5. Save the 10 recovery codes (Copy or Download .txt) somewhere safe, away from the phone: you see them only once.

When you turn it on, the other sessions open with your account are closed (the one you used stays) and you get an email.

In the app the account shows up with your brand name (Settings › Your brand) and your email.

Signing in

After email and password the panel asks for the app code. If the phone offers it, it fills it in by itself. A code works only once and only for a few minutes after the password: if you wait too long, enter email and password again.

Without your phone, press Use a recovery code and enter one of the saved codes (upper case, lower case and dashes don't matter). Each code works once; when you sign in with a recovery code you get an email, and the panel tells you how many codes you have left.

Against guessing: after the right password there are at most 5 codes, then you start over; no more than 10 codes in 10 minutes for each person and no more than 30 wrong codes in 10 minutes from the same address (successful sign-ins don't count: people working behind the same address don't block each other). After 5 wrong codes with the right password the person gets an email: someone knows their password (at most one every 6 hours; it also stays in the activity log).

Recovery codes and a new phone

• New recovery codes (with an app code) creates 10 new codes: the old ones stop working. When 3 or fewer are left, the panel points it out.
• To move to a new phone: Turn off (with your password and an app or recovery code), then Turn on with the new phone.

Turning it off closes the other sessions and sends an email.

Making it required

In Settings › Security choose whether it is required for administrators and/or for customers (including the people in their teams). By default it is optional. The card also shows how many people already have it.

Whoever doesn't have it, at the next sign-in with a password, finds a page that can only turn it on: they scan the QR code, enter the code, save the recovery codes and then come in as usual. Until they do, the rest of the panel and of the panel API answers "turn on two-step verification first". People already signed in when you turn the requirement on stay in until their session ends.

If it is required and someone turns it off (to change phone), right after that the panel asks them to turn it on again.

Before making it required for administrators, turn it on for yourself.

Someone lost their phone and their codes

When you remove it, the person is signed out of all sessions, gets an email and next time signs in with the password alone (if it is required, they turn it on again right away). It stays in the panel log and in the customer's activity log, where the author shows as "Panel administrator" (or "Your provider" if a reseller removed it), without your email.

A reseller, with their API key, removes it from their customers but not from themselves: a person in their team may have created the key.

For an administrator (even the last one), on the panel server:

sudo koavm user-2fa-reset --email name@example.com

It works with the panel running too. If the database is busy the command says so: stop the panel with sudo systemctl stop koavm, run it again and start the panel with sudo systemctl start koavm. It works for any email of the panel, including a customer or a person in a team. The command also says what happens at the next sign-in: if verification is required for administrators, it must be turned on again after the password.

If no administrator can turn it on any more (for example because the secrets key is missing, see below), turn the requirement off from the server:

sudo koavm user-2fa-reset --togli-obbligo

It can be combined with --email. The requirement is turned back on from Settings › Security.

What doesn't change

• Panel API keys (customers') and /api/v1 keys (billing): they work as before, with no code.
• Sign-in links created by billing with the API key (POST /api/v1/vps/{id}/login-link and /clients/{id}/login-link): they come in without the second step, because billing has already authenticated the customer. Even when verification is required for customers.
• Sign-in with Prime Software ID ("Sign in as admin"): it already has its own two-step verification.
• Demo accounts and the public demo cannot turn it on and are never required to.

Where the secrets are

Each person's secret is stored in the database encrypted with a key kept in the data folder (/var/lib/koavm/totp.key): someone holding just the database cannot read it. The key goes into the panel copy and comes back with the restore (see Updates and versions). If the key is lost (for example when only the database is moved by hand), app codes can no longer be checked: sign in with a recovery code, which doesn't depend on the key, or remove the verification with koavm user-2fa-reset. While verifications are active the panel does not create a new key by itself in place of the lost one: if you find it, put it back and everything works again. If it is really lost, create a new one:

sudo koavm user-2fa-reset --nuova-chiave

New activations use the new key; people who had verification with the lost one sign in with a recovery code (or you remove it with --email) and then turn it on again. Each secret records which key encrypts it: the support report says how many are encrypted with another key.

Recovery codes are stored only as a fingerprint (hash): not even the panel can read them back.

The support report says how many administrators, customers and team members have verification on and whether the key is there; never the secrets.