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,14 +31,14 @@ 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,
    Nextcloud will not save the plain password, hence it's recommended to
    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,72 @@
+===============================
+Using two-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 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.
+
+.. 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.
+
+Recovery codes in case you lost your 2nd factor
+===============================================
+You should always generate backup codes for 2FA. If your 2nd factor device
+gets stolen or is not working, you will be able to use one of these codes to
+unlock your account. It effectively functions as a backup 2nd factor. To
+get the backup codes, go to your Personal Settings and look under Second-factor
+Auth settings. Choose *Generate backup codes*.
+
+.. figure:: images/2fa_backupcode_1.png
+     :alt: 2FA backup code generator
+
+You will then be presented with a list of one-time-use backup codes.
+
+.. figure:: images/2fa_backupcode_2.png
+     :alt: 2FA backup codes
+
+You should put these codes in a safe spot, somewhere you can find them. Don't
+put them together with your 2nd factor like your mobile phone but make sure that
+if you lose one, you still have the other. Keeping them at home is probably
+the best thing to do.
+
+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:
+
+.. 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.
+
+.. 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 client applications with two-factor authentication
+========================================================
+Once you have enabled 2FA, your clients will no longer be able to connect with
+just your password unless they also have support for two-factor authentication.
+To solve this, you should 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.