tyler/proxmox-backup
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: add initial TFA documentation

Browse Source 
better than nothing..

Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
This commit is contained in:
Thomas Lamprecht 2021-02-01 19:46:07 +01:00
parent ca953d831f
commit f9fcac51a5
1 changed files with 88 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
docs/user-management.rst
View File

@ -284,3 +284,91 @@ you can use the ``proxmox-backup-manager user permission`` command:
Path: /datastore/store1
- Datastore.Backup (*)
.. _user_tfa:
Two-factor authentication
-------------------------
Introduction
~~~~~~~~~~~~
Simple authentication requires only secret piece of evidence (one factor) that
a user can successfully claim a identiy (authenticate), for example, that you
are allowed to login as `root@pam` on a specific Proxmox Backup Server.
If the password gets stolen, or leaked in another way, anybody can use it to
login - even if they should not be allowed to do so.
With Two-factor authentication (TFA) a user is asked for an additional factor,
to proof his authenticity. The extra factor is different from a password
(something only the user knows), it is something only the user has, for example
a piece of hardware (security key) or an secret saved on the users smartphone.
This means that a remote user can never get hold on such a physical object. So,
even if that user would know your password they cannot successfully
authenticate as you, as your second factor is missing.
Available Second Factors
~~~~~~~~~~~~~~~~~~~~~~~~
You can setup more than one second factor to avoid that losing your smartphone
or security key permanently locks you out from your account.
There are three different two-factor authentication methods supported:
* TOTP (`Time-based One-Time Password <https://en.wikipedia.org/wiki/Time-based_One-Time_Password>`_).
A short code derived from a shared secret and the current time, it switches
every 30 seconds.
* WebAuthn (`Web Authentication <https://en.wikipedia.org/wiki/WebAuthn>`_).
A general standard for authentication. It is implemented by various security
devices like hardware keys or trusted platform modules (TPM) from a computer
or smart phone.
* Single use Recovery Keys. A list of keys which should either be printed out
and locked in a secure fault or saved digitally in a electronic vault.
Each key can be used only once, they are perfect for ensuring you are not
locked out even if all of your other second factors are lost or corrupt.
Setup
~~~~~
.. _user_tfa_setup_totp:
TOTP
^^^^
There is not server setup required, simply install a TOTP app on your
smartphone (for example, `FreeOTP <https://freeotp.github.io/>`_) and use the
Proxmox Backup Server web-interface to add a TOTP factor.
.. _user_tfa_setup_webauthn:
WebAuthn
^^^^^^^^
For WebAuthn to work you need to have two things:
* a trusted HTTPS certificate (for example, by using `Let's Encrypt
<https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_)
* setup the WebAuthn configuration (see *Configuration -> Authentication* in the
Proxmox Backup Server web-interface). This can be auto-filled in most setups.
Once you fullfilled both of those requirements, you can add a WebAuthn
configuration in the *Access Control* panel.
.. _user_tfa_setup_recovery_keys:
Recovery Keys
^^^^^^^^^^^^^
Recovery key codes do not need any preparation, you can simply create a set of
recovery keys in the *Access Control* panel.
.. note:: There can only be one set of single-use recovery keys per user at any
time.
TFA and Automated Access
~~~~~~~~~~~~~~~~~~~~~~~~
Two-factor authentication is only implemented for the web-interface, you should
use :ref:`API Tokens <user_tokens>` for all other use cases, especially
non-interactive ones (for example, adding a Proxmox Backup server to Proxmox VE
as a storage).