tfa docs: language fixup

Simplifies the introduction a bit and makes it more readable.
Also some other minor language fixes throughout the section.

Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
This commit is contained in:
Dylan Whyte 2021-03-04 15:02:27 +01:00 committed by Thomas Lamprecht
parent 1bed3aedc8
commit 207f763d1a
1 changed files with 28 additions and 27 deletions

View File

@ -293,20 +293,19 @@ Two-factor authentication
Introduction Introduction
~~~~~~~~~~~~ ~~~~~~~~~~~~
Simple authentication requires only secret piece of evidence (one factor) that With simple authentication, only a password (single factor) is required to
a user can successfully claim a identiy (authenticate), for example, that you successfully claim an identity (authenticate), for example, to be able to log in
are allowed to login as `root@pam` on a specific Proxmox Backup Server. as `root@pam` on a specific instance of Proxmox Backup Server. In this case, if
If the password gets stolen, or leaked in another way, anybody can use it to the password gets stolen or leaked, anybody can use it to log in - even if they
login - even if they should not be allowed to do so. should not be allowed to do so.
With Two-factor authentication (TFA) a user is asked for an additional factor, 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 to verify their authenticity. Rather than relying on something only the user
(something only the user knows), it is something only the user has, for example knows (a password), this extra factor requires something only the user has, for
a piece of hardware (security key) or an secret saved on the users smartphone. example, a piece of hardware (security key) or a secret saved on the user's
smartphone. This prevents a remote user from gaining unauthorized access to an
This means that a remote user can never get hold on such a physical object. So, account, as even if they have the password, they will not have access to the
even if that user would know your password they cannot successfully physical object (second factor).
authenticate as you, as your second factor is missing.
.. image:: images/screenshots/pbs-gui-tfa-login.png .. image:: images/screenshots/pbs-gui-tfa-login.png
:align: right :align: right
@ -315,24 +314,26 @@ authenticate as you, as your second factor is missing.
Available Second Factors Available Second Factors
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
You can setup more than one second factor to avoid that losing your smartphone You can set up multiple second factors, in order to avoid a situation in which
or security key permanently locks you out from your account. losing your smartphone or security key locks you out of your account
permanently.
There are three different two-factor authentication methods supported: Proxmox Backup Server supports three different two-factor authentication
methods:
* TOTP (`Time-based One-Time Password <https://en.wikipedia.org/wiki/Time-based_One-Time_Password>`_). * 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 A short code derived from a shared secret and the current time, it changes
every 30 seconds. every 30 seconds.
* WebAuthn (`Web Authentication <https://en.wikipedia.org/wiki/WebAuthn>`_). * WebAuthn (`Web Authentication <https://en.wikipedia.org/wiki/WebAuthn>`_).
A general standard for authentication. It is implemented by various security A general standard for authentication. It is implemented by various security
devices like hardware keys or trusted platform modules (TPM) from a computer devices, like hardware keys or trusted platform modules (TPM) from a computer
or smart phone. or smart phone.
* Single use Recovery Keys. A list of keys which should either be printed out * 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. and locked in a secure place or saved digitally in an electronic vault.
Each key can be used only once, they are perfect for ensuring you are not Each key can be used only once. These are perfect for ensuring that you are
locked out even if all of your other second factors are lost or corrupt. not locked out, even if all of your other second factors are lost or corrupt.
Setup Setup
@ -347,7 +348,7 @@ TOTP
:align: right :align: right
:alt: Add a new user :alt: Add a new user
There is not server setup required, simply install a TOTP app on your There is no server setup required. Simply install a TOTP app on your
smartphone (for example, `FreeOTP <https://freeotp.github.io/>`_) and use the smartphone (for example, `FreeOTP <https://freeotp.github.io/>`_) and use the
Proxmox Backup Server web-interface to add a TOTP factor. Proxmox Backup Server web-interface to add a TOTP factor.
@ -356,7 +357,7 @@ Proxmox Backup Server web-interface to add a TOTP factor.
WebAuthn WebAuthn
^^^^^^^^ ^^^^^^^^
For WebAuthn to work you need to have two things: For WebAuthn to work, you need to have two things:
* a trusted HTTPS certificate (for example, by using `Let's Encrypt * a trusted HTTPS certificate (for example, by using `Let's Encrypt
<https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_) <https://pbs.proxmox.com/wiki/index.php/HTTPS_Certificate_Configuration>`_)
@ -364,7 +365,7 @@ For WebAuthn to work you need to have two things:
* setup the WebAuthn configuration (see *Configuration -> Authentication* in the * setup the WebAuthn configuration (see *Configuration -> Authentication* in the
Proxmox Backup Server web-interface). This can be auto-filled in most setups. 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 Once you have fulfilled both of these requirements, you can add a WebAuthn
configuration in the *Access Control* panel. configuration in the *Access Control* panel.
.. _user_tfa_setup_recovery_keys: .. _user_tfa_setup_recovery_keys:
@ -376,7 +377,7 @@ Recovery Keys
:align: right :align: right
:alt: Add a new user :alt: Add a new user
Recovery key codes do not need any preparation, you can simply create a set of Recovery key codes do not need any preparation; you can simply create a set of
recovery keys in the *Access Control* panel. recovery keys in the *Access Control* panel.
.. note:: There can only be one set of single-use recovery keys per user at any .. note:: There can only be one set of single-use recovery keys per user at any
@ -385,7 +386,7 @@ recovery keys in the *Access Control* panel.
TFA and Automated Access TFA and Automated Access
~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~
Two-factor authentication is only implemented for the web-interface, you should Two-factor authentication is only implemented for the web-interface. You should
use :ref:`API Tokens <user_tokens>` for all other use cases, especially 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 non-interactive ones (for example, adding a Proxmox Backup Server to Proxmox VE
as a storage). as a storage).