From 95469bf7fe90f6cd527fcd9b10a7c9fc0aa433c1 Mon Sep 17 00:00:00 2001
From: Christoph Wurst <ChristophWurst@users.noreply.github.com>
Date: Thu, 22 Nov 2018 09:54:29 +0100
Subject: [PATCH] Revamp 2FA admin docs (#932)

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
---
 .../configuration_user/two_factor-auth.rst    | 44 ++++++++++++++++---
 1 file changed, 38 insertions(+), 6 deletions(-)

diff --git a/admin_manual/configuration_user/two_factor-auth.rst b/admin_manual/configuration_user/two_factor-auth.rst
index 67b96160b..9e669eff6 100644
--- a/admin_manual/configuration_user/two_factor-auth.rst
+++ b/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
@@ -21,6 +27,32 @@ you want, 2FA will be installed and enabled on your Nextcloud server.
 
 .. figure:: ../images/2fa-app-install.png
 
+.. TODO: new screenshot
+
 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.
+
+ .. TODO: screenshot
+
+
+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.