Revamp 2FA admin docs

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>

admin_manual/configuration_server/occ_command.rst

@@ -1395,14 +1395,22 @@ Two-factor authentication
 If a two-factor provider app is enabled, it is enabled for all users by default
 (though the provider can decide whether or not the user has to pass the challenge).
 In the case of an user losing access to the second factor (e.g. lost phone with
-two-factor SMS verification), the admin can temporarily disable the two-factor
+two-factor SMS verification), the admin can try to disable the two-factor
 check for that user via the occ command::
 
- sudo -u www-data php occ twofactor:disable <username>
+ sudo -u www-data php occ twofactor:disable <uid> <provider_id>
+
+.. note:: This is not supported by all providers. For those that don't support
+  this operation, the `Two-Factor Admin Support app <https://apps.nextcloud.com/apps/twofactor_admin>`_
+  should be used where users get a one-time code to log into their account.
 
 To re-enable two-factor auth again use the following commmand::
 
- sudo -u www-data php occ twofactor:enable <username>
+ sudo -u www-data php occ twofactor:enable <uid> <provider_id>
+
+.. note:: This is not supported by all providers. For those that don't support
+  this operation, the `Two-Factor Admin Support app <https://apps.nextcloud.com/apps/twofactor_admin>`_
+  should be used where users get a one-time code to log into their account.
 
 .. _disable_user_label:
 

admin_manual/configuration_user/two_factor-auth.rst

@@ -1,17 +1,23 @@
 =========================
-Two factor authentication
+Two-factor authentication
 =========================
 
-Starting with Nextcloud 10, it is possible to use two factor authentication
-(2FA) with Nextcloud. It is a plugin based system requiring a 2FA app.
+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 official and 3rd-party Nextcloud apps.
+
+
 Several 2FA apps are already available including
 `TOTP <https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm>`_, 
-SMS 2-factor and `U2F <https://en.wikipedia.org/wiki/Universal_2nd_Factor>`_. 
-Developers can `built new two-factor provider apps <https://docs.nextcloud.com/server/14/developer_manual/app/two-factor-provider.html>`_.
+a Telegram/Signal/SMS gateway and `U2F <https://en.wikipedia.org/wiki/Universal_2nd_Factor>`_. 
+
+
+Developers can `build new two-factor provider apps <https://docs.nextcloud.com/server/14/developer_manual/app/two-factor-provider.html>`_.
 
 .. TODO ON RELEASE: Update version number above on release
 
-Enabling two factor authentication
+Enabling two-factor authentication
 ----------------------------------
 
 You can enable 2FA by installing and enabling a 2FA app like TOTP which works
@@ -24,3 +30,32 @@ you want, 2FA will be installed and enabled on your Nextcloud server.
 Once 2FA has been enabled, users have to `activate it in their personal settings. <https://docs.nextcloud.com/server/14/user_manual/user_2fa.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. Since Nextcloud 15 have the option to enforce the use of 2FA.
+
+
+Enforcement is possible systemwide (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.
+
+.. 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.
+
+.. note:: Should users lose access to their second factor and backup codes,
+  they won't be able to log into their account anymore. As administrator, you
+  can use the `Two-Factor Admin Support app <https://apps.nextcloud.com/apps/twofactor_admin>`_
+  to generate a one-time code for them to log in and unlock their account.
+  You can find out more about the app in its `documentation <https://nextcloud-twofactor-admin.readthedocs.io/en/latest/>`_

developer_manual/app/two-factor-provider.rst

@@ -4,15 +4,12 @@ Two-factor providers
 
 .. sectionauthor:: Christoph Wurst <christoph@owncloud.com>
 
-Two-factor auth providers apps are used to plug custom second factors into the Nextcloud core. The following
-code was taken from the `two-factor test app`_.
-
-.. _`two-factor test app`: https://github.com/ChristophWurst/twofactor_test
+Two-factor auth providers apps are used to plug custom second factors into the Nextcloud core.
 
 Implementing a simple two-factor auth provider
 ----------------------------------------------
 
-Two-factor auth providers must implement the ``OCP\Authentication\TwoFactorAuth\IProvider`` interface. The
+Two-factor auth providers must implement the ``OCP\Authentication\TwoFactorAuth\IProvider <https://github.com/nextcloud/server/blob/master/lib/public/Authentication/TwoFactorAuth/IProvider.php>``_ interface. The
 example below shows a minimalistic example of such a provider.
 
 .. code-block:: php
@@ -94,6 +91,23 @@ example below shows a minimalistic example of such a provider.
 
 	}
 
+Register the provider state
+---------------------------
+
+To always know if a provider is enabled for a user, the server persists the enabled/disabled state
+of each provider-user tuple. Hence a provider app has to propagate these state changes. This is
+handled by the `provider registry <https://github.com/nextcloud/server/blob/master/lib/public/Authentication/TwoFactorAuth/IRegistry.php>`_.
+
+You can have the registry injected via constructor dependency injection. Whenever the provider state
+is changed (user enables/disables the provider), the ``enableProviderFor`` or ``disableProviderFor``
+method must be called.
+
+
+.. note:: This provider registry was added in Nextcloud 14. For backwards compatibility, the server
+  still occasionally uses the ``IProvider::isTwoFactorAuthEnabledForUser`` method if the provider state
+  has not been set yet. This method will be removed in future releases.
+
+
 Registering a two-factor auth provider
 --------------------------------------
 
@@ -105,3 +119,38 @@ providers are registered via ``info.xml``.
 	<two-factor-providers>
 		<provider>OCA\TwoFactor_Test\Provider\TwoFactorTestProvider</provider>
 	</two-factor-providers>
+
+Providing an icon (optional)
+----------------------------
+
+To enhance how a provider is shown in the list of selectable providers on the login page, an icon
+can be specified. For that the provider class must implement the ``IProvidesIcons <https://github.com/nextcloud/server/blob/master/lib/public/Authentication/TwoFactorAuth/IProvidesIcons.php>``_
+interface. The light icon will be used on the login page, whereas the dark one will be placed next
+to the heading of the optional personal settings (see below).
+
+
+Provide personal settings (optional)
+------------------------------------
+
+Like other Nextcloud apps, two-factor providers often require user configuration to work. In Nextcloud
+15 a new, consolidated two-factor settings section was added. To add personal provider settings there,
+a provider must implement the ``IProvidesPersonalSettings <https://github.com/nextcloud/server/blob/master/lib/public/Authentication/TwoFactorAuth/IProvidesPersonalSettings.php>``_
+interface.
+
+
+Make a provider activatable by the admin (optional)
+---------------------------------------------------
+
+In order to make it possible for an admin to enable the provider for a given user via the occ
+command line tool, it's necessary to implement the ``OCP\Authentication\TwoFactorAuth\IActivatableByAdmin <https://github.com/nextcloud/server/blob/master/lib/public/Authentication/TwoFactorAuth/IActivatableByAdmin.php>``_
+interface. As described in the linked interface documentation, this should only be implemented
+for providers that need no user interaction when activated.
+
+
+Make a provider deactivatable by the admin (optional)
+-----------------------------------------------------
+
+In order to make it possible for an admin to disable the provider for a given user via the occ
+command line tool, it's necessary to implement the ``OCP\Authentication\TwoFactorAuth\IDeactivatableByAdmin <https://github.com/nextcloud/server/blob/master/lib/public/Authentication/TwoFactorAuth/IDeactivatableByAdmin.php>``_
+interface. As described in the linked interface documentation, this should only be implemented
+for providers that need no user interaction when deactivated.

user_manual/user_2fa.rst

@@ -19,7 +19,7 @@ Configuring two-factor authentication
 -------------------------------------
 
 In your Personal Settings look up the Second-factor Auth setting. In this
-example this is TOTP, a Google Authenticator compatible time based code.
+example this is TOTP, a Google Authenticator compatible time-based code.
 
 .. figure:: images/totp_enable.png
      :alt: TOTP configuration.
@@ -55,8 +55,15 @@ Logging in with two-factor authentication
 -----------------------------------------
 
 After you have logged out and need to log in again, you will see a request to
-enter the TOTP code in your browser. Just enter your code:
-  
+enter the TOTP code in your browser. If you enable not only the TOTP factor
+but another one, you will see a selection screen on which you can choose
+two-factor method for this login. Select TOTP.
+
+.. figure:: images/totp_login_1.png
+     :alt: Choosing a two-factor authentication method.
+
+Now, just enter your code:
+
 .. figure:: images/totp_login_2.png
      :alt: Entering TOTP code at login.