create 2FA documentation

admin_manual/configuration_user/index.rst

@@ -9,6 +9,7 @@ User Management
     reset_admin_password
     reset_user_password
     user_password_policy
+    two_factor-auth
     user_auth_ftp_smb_imap
     user_auth_ldap
     user_auth_ldap_cleanup

admin_manual/configuration_user/two_factor-auth.rst

@@ -0,0 +1,23 @@
+=========================
+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.
+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/11/developer_manual/app/two-factor-provider.html>`_.
+.. TODO ON RELEASE: Update version number above on release
+
+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.
+
+.. figure:: ../images/2fa-app-install.png
+
+Once 2FA has been enabled, users have to `activate it in their personal settings. <https://docs.nextcloud.com/server/11/user_manual/user_2fa.html>`_
+.. TODO ON RELEASE: Update version number above on release

user_manual/contents.rst

@@ -14,6 +14,7 @@ Table of Contents
     pim/index
     documents
     userpreferences
+    user_2fa
     session_management
     external_storage/index
     

user_manual/session_management.rst

@@ -10,7 +10,7 @@ Managing Connected Browsers
 In the list of connected browsers you see which browsers connected to your
 account recently:
 
-  .. figure:: images/settings_sessions.png
+.. figure:: images/settings_sessions.png
      :alt: List of browser sessions.
 
 You can use the trash icon to disconnect any of the browsers in the list.
@@ -20,7 +20,7 @@ Managing Devices
 In the list of connected devices you see all the devices and clients you
 generated a device password for and their last activity:
 
-  .. figure:: images/settings_devices.png
+.. figure:: images/settings_devices.png
      :alt: List of connected devices.
 
 You can use the trash icon to disconnect any of the devices in the list.
@@ -31,7 +31,7 @@ password is used for configuring the new client. Ideally, generate individual
 tokens for every device you connect to your account, so you can disconnect
 those individually if necessary.
 
-  .. figure:: images/settings_devices_add.png
+.. figure:: images/settings_devices_add.png
      :alt: Adding a new device.
 
 .. note:: You have only access to the device password when creating it,
@@ -39,6 +39,6 @@ those individually if necessary.
    enter the password on the new client immediately.
 
 
-.. note:: If two-factor authentication is enabled for your account,
+.. note:: If you are :doc:`user_2fa` for your account,
    device-specific passwords are the only way to configure clients. The
    client will deny connections of clients using your login password then.

user_manual/user_2fa.rst

@@ -0,0 +1,57 @@
+=============================
+Using 2 Factor Authentication
+=============================
+
+Two Factor Authentication (2FA) is a way to protect your Nextcloud account
+against unauthorized access. It works by requiring two different 'proofs' of
+your identity. For example, *something you know* (like a password) and 
+*something you have* like a physical key. Typically, the first factor is a
+password like you already have and the second can be a text message you
+receive or a code you generate on your phone or another device
+(*something you have*). Nextcloud supports a variety of 2nd factors and
+more can be added.
+
+Once a Two Factor Authentication app has been enabled by your administrator
+you can enable and configure it in :doc:`userpreferences`. Below you can
+see how.
+
+Configuring 2 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.
+  
+.. figure:: images/totp_enable.png
+     :alt: TOTP configuration.
+
+You will see your secret and a QR code which can be scanned by the TOTP app
+on your phone (or another device). Depending on the app or tool, type in the
+code or scan the QR and your device will show a login code which changes
+every 30 seconds.
+
+Logging in with 2 Factor Authentication
+=======================================
+After you have logged out and need to log in again, you will see a
+*2FA challenge*, a request to enter the TOTP code in your browser.
+  
+.. figure:: images/totp_login_1.png
+     :alt: TOTP challenge at login.
+
+Click on *Authenticate with a TOTP app* and enter your code:
+  
+.. figure:: images/totp_login_2.png
+     :alt: Entering TOTP code at login.
+
+If the code was correct you will be redirected to your Nextcloud account.
+You will not have to enter the code again in this browser unless you clear
+the browser cookies.
+
+.. note:: Since the code is time-based, it’s important that your server’s and
+your smartphone’s clock are almost in sync. A time drift of a few seconds
+won’t be a problem.
+
+Using clients with 2 Factor Authentication
+==========================================
+Once you have enabled 2FA, your clients will no longer be able to connect
+unless they also have support for 2 Factor Authentication. However, you can
+generate device specific passwords for them. See :doc:`session_management` for
+more information on how to do this.

user_manual/userpreferences.rst

@@ -34,6 +34,7 @@ include the following.
 * Email address.
 * Lists your Group memberships.
 * Manage your password.
+* :doc:`user_2fa`.
 * :doc:`userpreferences`.
 * Choose the language for your Nextcloud interface.
 * Links to desktop and mobile apps.