Merge pull request #12446 from nextcloud/jtr/admin-refactor-2fa

refactor(admin): 2FA chapter clean-up

Author: susnux

admin_manual/configuration_user/two_factor-auth.rst

@@ -5,57 +5,64 @@ Two-factor authentication
 =========================
 
 Two-factor authentication adds an additional layer of security to user accounts. In order to log
-in on an account with two-factor authentication (2FA) enabled, it is necessary to provide both the
-login password and another factor. 2FA in Nextcloud is pluggable, meaning that they are not part
-of the Nextcloud Server component but provided by featured and 3rd-party Nextcloud apps.
+in on an account when two-factor authentication (2FA) enabled, you must provide both the
+login password and another factor. 
 
+To use 2FA two things must happen:
 
-Several 2FA apps are already available including
-`TOTP <https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm>`_, 
-a Telegram/Signal/SMS gateway and `U2F <https://en.wikipedia.org/wiki/Universal_2nd_Factor>`_. 
+- At least one 2FA provider must be enabled by the administrator.
+- A user must activate 2FA on their account (or) the administrator must enforce the use of 2FA.
 
-
-Developers can `build new two-factor provider apps <https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/two-factor-provider.html>`_.
-
-.. TODO ON RELEASE: Update version number above on release
+Both steps are described below.
 
 Enabling two-factor authentication
 ----------------------------------
 
-You can enable 2FA by installing and enabling a 2FA app like TOTP which works
-with Google Authenticator and compatible apps. The apps are available in the
-Nextcloud App store so by navigating there and clicking **enable** for the app
-you want, 2FA will be installed and enabled on your Nextcloud server.
+2FA in Nextcloud is pluggable, meaning that various 2FA providers can be used to support different 
+types of factors. Three providers are automatically installed (but may need to be enabled):
 
-.. figure:: ../images/2fa-app-install.png
+**Two-Factor TOTP Provider**
 
-Once 2FA has been enabled, users have to `activate it in their personal settings. <https://docs.nextcloud.com/server/latest/user_manual/en/user_2fa.html>`_
+- A 2FA factor provider that enables the use of a `TOTP <https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm>`_
+  (RFC 6238) app installed on a phone (or other device) to be used as the secondary factor
+- Compatible with any RFC 6238 compliant TOTP client app (such as `Aegis <https://github.com/beemdevelopment/aegis>`_ or Google Authenticator).
+- Disabled by default. Go to *Apps->Disabled apps* and find *Two-Factor TOTP Provider* to enable this factor.
 
-.. TODO ON RELEASE: Update version number above on release
+**Two-Factor Authentication via Nextcloud notifications**
 
-Disabling two-factor authentication
------------------------------------
+- A 2FA factor provider that enables the use of a logged in device as the secondary factor.
+- Disabled by default. Go to *Apps->Disabled apps* and find *Two-Factor Authentication via Nextcloud 
+  notification* to enable this factor.
 
-Two-factor providers can be disabled via :ref:`occ <occ>`::
+**Two-Factor Backup Codes**
 
- sudo -u www-data php occ twofactorauth:disable <uid> <provider_id>
+- A special 2FA factor provider enables users to generate backup codes provider.
+- Facilitates recovery of access if a a 2FA device is unavailable (i.e. gets stolen or is not working).
+- Generates ten backup codes (which can, of course, only be use once).
+- Always enabled.
 
-User are free to enable this provider again via their personal settings.
+Other 2FA providers may be found in the App Store. 
 
-.. note:: This operation has to be supported by the provider. If this support is missing, Nextcloud will abort and show an error.
+.. TODO ON RELEASE: Update version number above on release
+
+.. figure:: ../images/2fa-app-install.png
+
+Developers can also `implement new two-factor provider 
+apps <https://docs.nextcloud.com/server/latest/developer_manual/digging_deeper/two-factor-provider.html>`_.
+
+.. TODO ON RELEASE: Update version number above on release
 
 Enforcing two-factor authentication
 -----------------------------------
 
 By default 2FA is *optional*, hence users are given the choice whether to enable
-it for their account. Admins may enforce the use of 2FA.
+it for their account `under their personal settings <https://docs.nextcloud.com/server/latest/user_manual/en/user_2fa.html>`_.
+Admins may, however, enforce the use of 2FA.
 
+Enforcement is possible system-wide (all users) or for selected groups only. Select groups
+can also be excluded from 2FA requirements. 
 
-Enforcement is possible system-wide (all users), for selected groups only and can
-also be excluded for certain groups.
-
-
-These settings can be found in the administrator's security settings.
+These settings can be found under *Administration Settings->Security*.
 
 .. figure:: ../images/2fa-admin-settings.png
 
@@ -69,10 +76,29 @@ a user has 2FA enforced:
 Provider removal
 ----------------
 
-Nextcloud keeps records about the enabled two-factor authentication providers of every user. If a provider is simply removed/:ref:`disabled <apps_commands_label>`, Nextcloud will still consider the provider active for the user at login and show a warning like *Could not load at least one of your enabled two-factor auth methods*.
+Nextcloud keeps records about the enabled two-factor authentication providers of every user.
+If a provider is simply removed/:ref:`disabled <apps_commands_label>`,
+Nextcloud will still consider the provider active for the user at login and show a warning like *Could not load at least one of your enabled two-factor auth methods*.
 
 The associations of removed providers can be cleaned up via :ref:`occ <occ>`::
 
  sudo -u www-data php occ twofactorauth:cleanup <provider_id>
 
-.. warning:: This operation is irreversible. Only run it for providers you do not intend to enable again.
+.. warning:: This operation is irreversible. Only run it for providers you do not intend to enable again as then you have to setup the configuration for all users from scratch.
+
+
+Disabling two-factor authentication
+-----------------------------------
+
+Two-factor providers can be disabled via :ref:`occ <occ>`::
+
+ sudo -u www-data php occ twofactorauth:disable <uid> <provider_id>
+
+This can be useful if the user forgot or lost their second factor.
+Afterwards users are free to enable this provider again via their personal settings.
+
+.. note:: This operation has to be supported by the provider. If this support is missing, Nextcloud will abort and show an error.
+
+It is also possible to check the current two-factor user status via :ref:`occ <occ>`::
+
+  sudo -u www-data php occ twofactorauth:state <uid>