Protect sign-in with a one-time code

XOA-HL can ask for a 6-digit one-time code from an authenticator app after the password. The code changes with time (TOTP). Each account that signs in with a local password turns it on for itself. Try it first on a non-administrator account created for this test.

Before you begin

Your browser checks the code you type during setup, using its own clock. At sign-in, the appliance checks the code with its clock. So a code accepted during setup does not prove that the appliance’s time is correct.

Turn on a one-time code for your account

1. Sign in as the account to protect. Open your user page with the user icon in the menu (/#/user).
2. Find the OTP authentication switch and turn it on. The Add OTP authentication dialog shows a QR code and the secret as text.
3. Scan the QR code, or type the secret, in your authenticator app. The new entry is issued by Xen Orchestra and named after the account’s email or login.
4. Type the current code in OTP code and confirm. If the code is wrong, the dialog opens again: type the code that the app shows now. Cancel leaves the one-time code off.

If the switch is missing, stop and note the installed version. This build uses XO’s default open-source plan, which shows the switch, so a missing subscription is not the cause. Report the difference.

Check: the switch is on, and your user page shows the secret and its QR code next to it. Anyone who sees them can generate valid codes: do not share this page or take screenshots of it. This QR code names the issuer XenOrchestra (no space) for the same secret. Keep the entry you already have in your app; do not scan it again.

Check sign-in in a new session

1. Keep your current session open. Open a private browser window and sign in with your username and password.
2. A second page asks for a Code. Type the current code from the app and select Sign in.
3. A wrong or expired code shows Invalid code. Wait for the next code and try again.
4. Check that you are signed in to the right account, then close the private window.

Check: the sign-in asked for a code and accepted the right one. If it keeps failing, use the open session to remove the one-time code, check both clocks, then turn it on again.

What a one-time code does not protect

• Turning it on does not end existing sessions or revoke tokens. Every valid authentication token skips the code check, including tokens created later: tokens are separate credentials. After you turn it on, open Authentication tokens on your user page and delete the tokens you do not recognize or no longer need. A script that uses a deleted token stops working.
• It protects XO web sign-in for this account only. It does not protect SSH or console access to the appliance, XO Lite or the root account on the host, or other XO accounts.
• External sign-in providers and their own multi-factor authentication are not covered here.

Remove a one-time code

• Your own account: on your user page, turn off OTP authentication and confirm Remove OTP authentication.
• Another account, as an administrator: open Settings → Users. In the OTP column, select Remove for that account and confirm. First check who is asking, for example through another channel. The user can then set up a new device.

Accounts without a one-time code show Not configured in that column. If the only administrator loses the device, the interface offers no way back in. From the appliance console, you can still recover administrator access. A second administrator is simpler: keep one.

Check: the switch is off and the account’s OTP column shows Not configured. In a new private window, the account signs in with its local username and password and no code. Keep the recovery administrator signed in until you have confirmed this.