From fed4213d4509d3ea742fc1273959b6288b5de196 Mon Sep 17 00:00:00 2001 From: Josh Date: Mon, 16 Dec 2024 17:43:16 -0500 Subject: [PATCH] refactor(admin): 2FA chapter clean-up - Document the three bundled (shipped) 2FA providers. - Clarify what "providers" are and why they're important. - Re-order the sections. - Remove some outdated bits. - Eliminate some redundancies. - Misc tidying up. Signed-off-by: Josh --- .../configuration_user/two_factor-auth.rst | 76 ++++++++++++------- 1 file changed, 47 insertions(+), 29 deletions(-) diff --git a/admin_manual/configuration_user/two_factor-auth.rst b/admin_manual/configuration_user/two_factor-auth.rst index 478fc087bd9..639bf52a295 100644 --- a/admin_manual/configuration_user/two_factor-auth.rst +++ b/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, it is necessary to provide both the +login password and another factor. +To use 2FA two things must happen: -Several 2FA apps are already available including -`TOTP `_, -a Telegram/Signal/SMS gateway and `U2F `_. +- 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 `_. - -.. 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. `_ +- A 2FA factor provider that enables the use of a `TOTP `_ + (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 `_ 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 `:: +**Two-Factor Backup Codes** - sudo -u www-data php occ twofactorauth:disable +- A special 2FA factor provider enables users to generate backup codes provider. +- Faciliates 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 `_. + +.. 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. - - -Enforcement is possible system-wide (all users), for selected groups only and can -also be excluded for certain groups. +it for their account `under their personal settings `_. +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. -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 @@ -76,3 +83,14 @@ The associations of removed providers can be cleaned up via :ref:`occ `:: sudo -u www-data php occ twofactorauth:cleanup .. warning:: This operation is irreversible. Only run it for providers you do not intend to enable again. + +Disabling two-factor authentication +----------------------------------- + +Two-factor providers can be disabled via :ref:`occ `:: + + sudo -u www-data php occ twofactorauth:disable + +User 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.