USERDOCAP-721 Documentation support for MFA feature

- add screenshots

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

3 files changed, 92 insertions, 86 deletions

diff --git a/doc/book-enea-edge-getting-started/doc/images/mfa_first_time_setup.png b/doc/book-enea-edge-getting-started/doc/images/mfa_first_time_setup.png
new file mode 100644
index 0000000..c0230f5
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/mfa_first_time_setup.png
diff --git a/doc/book-enea-edge-getting-started/doc/images/mfa_login.png b/doc/book-enea-edge-getting-started/doc/images/mfa_login.png
new file mode 100644
index 0000000..79d9696
--- /dev/null
+++ b/doc/book-enea-edge-getting-started/doc/images/mfa_login.png
diff --git a/doc/book-enea-edge-getting-started/doc/security.xml b/doc/book-enea-edge-getting-started/doc/security.xml
index 9b8ec14..0812a2f 100644
--- a/doc/book-enea-edge-getting-started/doc/security.xml
+++ b/doc/book-enea-edge-getting-started/doc/security.xml
@@ -1,51 +1,62 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8"?>
 <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">
+    <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>
+
+    <note>
+      <para>Configuring MFA will only be possible using the Web interface, and
+      not the REST API. Users with MFA enabled will not be able to log
+      in through the REST API. If attempted, a <literal>401</literal> HTTP
+      code will be returned, with the <literal>EMS-Error</literal> header
+      containing the <literal>EMS_UserMFAEnabled</literal> error.</para>
+    </note>
+
+    <section id="config_mfa">
       <title>Configuring User MFA</title>
 
-      <para>The administrator must enable MFA authentication for the
-      desired new user by:</para>
-      
+      <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>
+          <para>Accessing the <emphasis role="bold">Security</emphasis>
+          tab.</para>
         </listitem>
-          
+
         <listitem>
-          <para>Accessing the <emphasis role="bold">Configuration</emphasis> menu.</para>
+          <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>
+          <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>
 
+      <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>
+      <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">
@@ -53,19 +64,30 @@
 
       <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
+      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>
+      in clear text ready for copying and manual entry, in case scanning the
+      QR code does not work.</para>
+
+      <figure>
+        <title>Initial setup for Multi-Factor login</title>
+
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" scale="60"
+                       fileref="images/mfa_first_time_setup.png" />
+          </imageobject>
+        </mediaobject>
+      </figure>
+
+      <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.
@@ -74,56 +96,40 @@
       Authenticator, this time, however, the secret will no longer be
       displayed.</para>
 
+      <figure>
+        <title>Second login</title>
+
+        <mediaobject>
+          <imageobject>
+            <imagedata align="center" scale="80"
+                       fileref="images/mfa_login.png" />
+          </imageobject>
+        </mediaobject>
+      </figure>
+
       <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>
+        <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>
+      <para>Multi Factor Authentication in the Enea Edge Management
+      application is supported only for Google Authenticator.</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>
+      <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>
-</chapter>
+</chapter>
\ No newline at end of file