mirror of
https://github.com/nextcloud/documentation.git
synced 2025-08-20 14:15:54 +00:00
495247ae4a
Use `sudo -E -u www-data php occ` everywhere. Motivation: this should work on more appliances like also inside docker containers. Signed-off-by: Simon L. <szaimen@e.mail.de>
105 lines
4.5 KiB
ReStructuredText
105 lines
4.5 KiB
ReStructuredText
.. _two-factor-auth:
|
|
|
|
=========================
|
|
Two-factor authentication
|
|
=========================
|
|
|
|
Two-factor authentication adds an additional layer of security to user accounts. In order to log
|
|
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:
|
|
|
|
- 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.
|
|
|
|
Both steps are described below.
|
|
|
|
Enabling two-factor authentication
|
|
----------------------------------
|
|
|
|
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):
|
|
|
|
**Two-Factor TOTP Provider**
|
|
|
|
- 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.
|
|
|
|
**Two-Factor Authentication via Nextcloud notifications**
|
|
|
|
- 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 Backup Codes**
|
|
|
|
- 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.
|
|
|
|
Other 2FA providers may be found in the App Store.
|
|
|
|
.. 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 `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.
|
|
|
|
These settings can be found under *Administration Settings->Security*.
|
|
|
|
.. figure:: ../images/2fa-admin-settings.png
|
|
|
|
When groups are selected/excluded, they use the following logic to determine if
|
|
a user has 2FA enforced:
|
|
|
|
* If no groups are selected, 2FA is enabled for everyone except members of the excluded groups
|
|
* If groups are selected, 2FA is enabled for all members of these. If a user is both in a
|
|
selected *and* excluded group, the selected takes precedence and 2FA is 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*.
|
|
|
|
The associations of removed providers can be cleaned up via :ref:`occ <occ>`::
|
|
|
|
sudo -E -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 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 -E -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 -E -u www-data php occ twofactorauth:state <uid>
|