Two-factor authentication

From BitFolk
Jump to: navigation, search

Using two-factor authentication (2FA) to improve security of your BitFolk Panel and Xen Shell accounts.


By default a simple user name and password protects your Panel and Xen Shell accounts. A person with access to these can boot into a rescue environment that has unrestricted access to your data. Security can be improved by enabling 2FA, which will then additionally require a valid TOTP token to be provided at login time for both Panel and SSH to Xen Shell.

Enabling 2FA


The first step is to install a TOTP client on a mobile device that you always have with you. Popular examples include Google Authenticator (Android, iOS), 1Password (Android, iOS), FreeOTP (Android, iOS), Ubuntu Authenticator (Ubuntu Touch), and others.


2FA is enabled from the security section of the Panel. The first time that you enable it, the secret key will be presented to you as both a QR code and a key string. The QR code is for easy enrolment into a mobile device through scanning. You can also just type the key string into the TOTP client though this is rather laborious.

You should keep a copy of the key string somewhere safe in case you ever need to enrol it into another mobile device.

You will now be asked to verify your ability to enter correct TOTP tokens. 2FA will not be enabled until you do so.

A green tick will appear once you've successfully entered a TOTP token and from this point on you will need to supply a valid TOTP token at each login to the Panel and at each password-based SSH login to your Xen Shell.

Password reset

Emailed password resets will be disabled while 2FA is in effect. If you forget your account password while 2FA is enabled then you're going to have to contact support to ask for 2FA to be disabled. This may take some time as support will need to satisfy themselves of your identity.

Disabling 2FA

You can disable 2FA from the security section. Your key data will be kept in case you want to enable it again later.

If you never want to use 2FA again or if you need to change your key then you can use the "Invalidate 2FA key" button. That removes all key data and disables 2FA, allowing you to generate a new key if you wish.

If you lose your mobile device

You can enrol your saved key into a new device.

If you didn't save the key string then you'll need to contact support to ask for 2FA to be disabled. This may take some time as support will need to satisfy themselves of your identity.

2FA and SSH

2FA also needs to apply to SSH logins to your Xen Shell, because that is protected by the same user name / password and allows for unrestricted access to your data. Bear in mind that as TOTP is based on a token that refreshes every 30 seconds, enabling it will rate-limit your SSH connections to one per 30 seconds.

All of this is only protecting SSH to the Xen Shell, not to your actual VPS. Your VPS is your own system and you can secure it how you wish. In theory there is no reason why you could not install something like the Google Authenticator PAM module and give it the same key as the one you have for your BitFolk 2FA, but this would be inadvisable as it would mean that BitFolk could calculate your one-time passwords too, and vice versa for anyone with access to your VPS's user account.

You may find securing your Xen Shell with SSH keys to be more convenient than 2FA. SSH key authentication will completely bypass 2FA.

There is currently no way to restrict Xen Shell SSH login to key only. Either key or password (plus 2FA if enabled) are sufficient. If you are not happy with password+2FA and want to see it set to key-only, please submit a feature request (log in with your usual BitFolk credentials).