Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor(admin): 2FA chapter clean-up #12446

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

refactor(admin): 2FA chapter clean-up #12446

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 47 additions & 29 deletions admin_manual/configuration_user/two_factor-auth.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it is necessary to provide -> you must provide
(direct language is often easier to understand)

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):
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about webauthn that let's you use U2F devices: https://apps.nextcloud.com/apps/twofactor_webauthn
Is this another method, or does it count as something different?


.. 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.


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 <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 in the administrator's security settings.
These settings can be found under *Administration Settings->Security*.

.. figure:: ../images/2fa-admin-settings.png

Expand All @@ -76,3 +83,14 @@ 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sound a bit like you can never use it again. It's just the current settings are all lost, and if you enable it you have to set up everything again (might be interesting for people who have messed up something with their setup)?


Disabling two-factor authentication
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For me the use case is, that a user has forgotten/lost their second factor. If there are different factors possible, I'd add a line to show 2FA status of the user first:
sudo -u www-data php occ twofactorauth:state <uid>

-----------------------------------

Two-factor providers can be disabled via :ref:`occ <occ>`::

sudo -u www-data php occ twofactorauth:disable <uid> <provider_id>

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.