USERDOCAP-721 Documentation support for MFA feature

Change-Id: I7410824c38166c1a66ffd32cbfb5728c607b744c
Signed-off-by: tombil <toma.bilius@enea.com>

2 files changed, 133 insertions, 1 deletions

diff --git a/doc/book-enea-edge-getting-started/doc/book.xml b/doc/book-enea-edge-getting-started/doc/book.xml
index e74ac85..9585329 100644
--- a/doc/book-enea-edge-getting-started/doc/book.xml
+++ b/doc/book-enea-edge-getting-started/doc/book.xml
@@ -38,8 +38,11 @@
 
   <xi:include href="submaps.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
+  <xi:include href="security.xml"
+              xmlns:xi="http://www.w3.org/2001/XInclude" />
+
   <xi:include href="grafana.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <xi:include href="troubleshooting.xml"
               xmlns:xi="http://www.w3.org/2001/XInclude" />
-</book>
\ No newline at end of file
+</book>
diff --git a/doc/book-enea-edge-getting-started/doc/security.xml b/doc/book-enea-edge-getting-started/doc/security.xml
new file mode 100644
index 0000000..9b8ec14
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/security.xml
@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<chapter id="security">
+  <title>Security</title>
+
+  <section id="mfa_security">
+    <title>Authenticating using Multi-Factor Authentication</title>
+
+    <para>Enea Edge Management provides the ability to authenticate using the MFA
+    authentication method. This is offered as a two-step procedure: first, the
+    user enters the local user/password credentials. Then the security token generated 
+    by Google Authenticator must be introduced. This is based on a shared secret between the 
+    Enea Edge Management and the Google Authenticator applications. The shared secret is a 
+    32 character long string that is presented to the user upon first login as a character 
+    sequence and a QR code.
+    </para>
+
+    <section id ="config_mfa">
+      <title>Configuring User MFA</title>
+
+      <para>The administrator must enable MFA authentication for the
+      desired new user by:</para>
+      
+      <orderedlist>
+        <listitem>
+          <para>Accessing the <emphasis role="bold">Security</emphasis> tab.</para>
+        </listitem>
+          
+        <listitem>
+          <para>Accessing the <emphasis role="bold">Configuration</emphasis> menu.</para>
+        </listitem>
+        
+        <listitem>
+          <para>Selecting the <emphasis role="bold">Add</emphasis> option, entering the 
+            details for the new user and then enabling the 
+            <emphasis role="bold">Enable MFA Login</emphasis> checkbox.</para>
+        </listitem>
+      </orderedlist>
+      
+      <para>It is also possible to enable/disable MFA for existing users by selecting
+      the user and checking/unchecking the Enable MFA Login checkbox in the
+      right-hand side panel. Disabling MFA for a user will also clear the
+      secret from the database, therefore upon reenabling it the user will be
+      asked to configure a new shared secret. For more details on how to configure
+      a new shared secret, please see the following section.</para>
+
+
+      <note><para>All MFA information for enabled users will be preserved upon upgrading the
+        Enea Edge Management application.</para></note>
+    </section>
+
+    <section id="security_authentication">
+      <title>Security Authentication</title>
+
+      <para>Before the user logs in, there is no secret set in the Enea Edge
+      Management database. Initially, the user will enter his credentials as
+      in a normal, local authentication. He will then be redirected to a 
+        second page that presents the secret as a QR code, that he must scan
+      using the Google Authenticator application. The secret is also presented
+      in clear text ready for copying and manual entry, in case scanning 
+        the QR code does not work.</para>
+      
+      <para>Once the scanning or manual entry is completed successfully, the 
+        Edge Management and Google Authenticator applications have the same 
+        secret configured. The Authenticator application will then offer a security
+      token as a six digit number that the user must enter on the same page,
+      in the Enea Edge Management application. If the token is correct, 
+        authentication is successful. The six digit token is available for a maximum of 
+      30 seconds.</para>
+
+      <para>Once the initial login succeeds and the secret is saved in the
+      database, subsequent logins will still be done using a two-step method.
+      The user will provide first his classic credentials, and then, on the
+      second page he will enter the token as generated by Google
+      Authenticator, this time, however, the secret will no longer be
+      displayed.</para>
+
+      <note>
+        <para>If the shared secret is ever lost, it can always be regenerated, but
+          only upon request to the administrator. It is done by accessing 
+          the <emphasis role="bold">Security</emphasis> tab, selecting 
+          the <emphasis role="bold">Configuration</emphasis> menu and choosing 
+          the user, and on the right-hand side panel unchecking the
+          <emphasis role="bold">Enable MFA Login</emphasis> checkbox. Then 
+          pressing the <emphasis role="bold">Apply</emphasis> button, checking it 
+          again, and clicking <emphasis role="bold">Apply</emphasis> one final time. When 
+          the MFA Login is disabled, the secret is also erased from the database.
+        </para>
+       </note>
+    </section>
+
+    <section id="token_generators">
+      <title>Supported Token Generators</title>
+
+      <para>Multi Factor Authentication in the Enea Edge Management application is 
+        supported only for Google Authenticator.
+      </para>
+
+      <para>The time on the server hosting the Enea Edge Management application 
+        and the device holding the Authenticatior application must be synchronized, 
+        within an error margin of 30 seconds.</para>
+    </section>
+
+    <section id="mfa_limitations">
+      <title>MFA Limitations</title>
+      
+      <para>The following is a brief list of the limitations currently affecting 
+        MF Authentication:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Configuring MFA will only be possible using the Web interface,
+          and not the REST API.</para>
+        </listitem>
+
+        <listitem>
+          <para>Users with MFA enabled will not be able to log in using the
+          REST API. In this case, a <literal>401</literal> HTTP code will be
+          returned, with the <literal>EMS-Error</literal> header containing
+          the <literal>EMS_UserMFAEnabled</literal> error.</para>
+        </listitem>
+
+        <listitem>
+          <para>MFA authentication will not be supported using the RADIUS or
+          LDAP AAA methods.</para>
+        </listitem>
+      </itemizedlist>
+    </section>
+  </section>
+</chapter>