| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <chapter xml:id="totp-auth" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" |
| xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink"> |
| <title>TOTP two-factor authentication</title> |
| <indexterm> |
| <primary>TOTP</primary> |
| </indexterm> |
| <para>Guacamole supports TOTP as a second authentication factor, layered on top of any other |
| authentication extension, including those available from the main project website, providing |
| <link linkend="totp-prerequisites">base requirements for key storage and |
| enrollment</link> are met. The TOTP authentication extension allows users to be |
| additionally verified against a user-specific and secret key generated during <link |
| linkend="totp-enrollment">enrollment of their authentication device</link>.</para> |
| <important> |
| <para>This chapter involves modifying the contents of <varname>GUACAMOLE_HOME</varname> - |
| the Guacamole configuration directory. If you are unsure where |
| <varname>GUACAMOLE_HOME</varname> is located on your system, please consult <xref |
| linkend="configuring-guacamole"/> before proceeding.</para> |
| </important> |
| <section xml:id="totp-prerequisites"> |
| <title>Prerequisites</title> |
| <para>The enrollment process used by Guacamole's TOTP support needs to be able to store an |
| automatically-generated key within the user's account, and will be operating with the |
| privileges of that user when it does so. With this in mind, there are requirements which |
| must be satisfied for TOTP to work as expected:</para> |
| <itemizedlist> |
| <listitem> |
| <para>Another extension must be installed which supports storage of arbitrary data |
| from other extensions. <emphasis>Currently the only extensions provided with |
| Guacamole which support this kind of storage are the <link |
| linkend="jdbc-auth">database authentication |
| extensions</link>.</emphasis></para> |
| </listitem> |
| <listitem> |
| <para>Within whichever extension provides the storage described above, users |
| requiring TOTP must be granted permission to update their own accounts (to |
| update their passwords, etc.). This privilege is managed within the <link |
| linkend="user-management">administrative web interface</link> with a |
| checkbox labeled "change own password". <emphasis>If a user lacks this |
| permission, the TOTP extension will not be able to generate and store the |
| user's TOTP key during enrollment, and TOTP will be disabled for that |
| user.</emphasis></para> |
| </listitem> |
| </itemizedlist> |
| <para>It is thus recommended that authentication against a database be fully configured |
| prior to setting up TOTP. Instructions walking through the setup of database |
| authentication for Guacamole are provided in <xref linkend="jdbc-auth"/>.</para> |
| </section> |
| <section xml:id="totp-architecture"> |
| <title>How TOTP works with Guacamole</title> |
| <para>Guacamole provides support for TOTP as a second authentication factor. To make use of |
| the TOTP authentication extension, some other authentication mechanism will need be |
| configured, as well. When a user attempts to log into Guacamole, other installed |
| authentication methods will be queried first:</para> |
| <informalfigure> |
| <mediaobject> |
| <imageobject> |
| <imagedata fileref="images/totp-auth-factor-1.png" format="PNG" |
| contentwidth="2in"/> |
| </imageobject> |
| </mediaobject> |
| </informalfigure> |
| <para>Only after authentication has succeeded with one of those methods will Guacamole |
| prompt the user to further verify their identity with an authentication code:</para> |
| <informalfigure> |
| <mediaobject> |
| <imageobject> |
| <imagedata fileref="images/totp-auth-factor-2.png" format="PNG" |
| contentwidth="4in"/> |
| </imageobject> |
| </mediaobject> |
| </informalfigure> |
| <para>If both the initial authentication attempt and verification using TOTP succeed, the |
| user will be allowed in. If either mechanism fails, access to Guacamole is |
| denied.</para> |
| <section xml:id="totp-enrollment"> |
| <title>Enrollment</title> |
| <para>If the user does not yet have a TOTP key associated with their account (they have |
| not yet completed enrollment), they be required to enroll an authentication device |
| after passing the first authentication factor. A QR code containing an |
| automatically-generated key will be presented to the user to be scanned by their |
| authentication app or device:</para> |
| <mediaobject> |
| <imageobject> |
| <imagedata fileref="images/totp-enroll.png" format="PNG" contentwidth="4in"/> |
| </imageobject> |
| </mediaobject> |
| <para>If the authentication device does not support scanning QR codes for enrollment, |
| the details within the QR code can be revealed by clicking the "Show" link next to |
| the "Details" header. These values can then be entered manually:</para> |
| <mediaobject> |
| <imageobject> |
| <imagedata fileref="images/totp-enroll-detail.png" format="PNG" |
| contentwidth="4in"/> |
| </imageobject> |
| </mediaobject> |
| <para>Enrollment is completed once the user enters a valid authentication code generated |
| by their device using the provided key.</para> |
| </section> |
| </section> |
| <section xml:id="totp-downloading"> |
| <title>Downloading the TOTP extension</title> |
| <para>The TOTP authentication extension is available separately from the main |
| <filename>guacamole.war</filename>. The link for this and all other |
| officially-supported and compatible extensions for a particular version of Guacamole are |
| provided on the release notes for that version. You can find the release notes for |
| current versions of Guacamole here: <link |
| xlink:href="http://guacamole.apache.org/releases/" |
| >http://guacamole.apache.org/releases/</link>.</para> |
| <para>The TOTP authentication extension is packaged as a <filename>.tar.gz</filename> file |
| containing only the extension itself, |
| <filename>guacamole-auth-totp-1.1.0.jar</filename>, which must ultimately be placed in |
| <filename>GUACAMOLE_HOME/extensions</filename>.</para> |
| </section> |
| <section xml:id="installing-totp-auth"> |
| <title>Installing TOTP authentication</title> |
| <para>Guacamole extensions are self-contained <filename>.jar</filename> files which are |
| located within the <filename>GUACAMOLE_HOME/extensions</filename> directory. To install |
| the TOTP authentication extension, you must:</para> |
| <procedure> |
| <step> |
| <para>Create the <filename>GUACAMOLE_HOME/extensions</filename> directory, if it |
| does not already exist.</para> |
| </step> |
| <step> |
| <para>Copy <filename>guacamole-auth-totp-1.1.0.jar</filename> within |
| <filename>GUACAMOLE_HOME/extensions</filename>.</para> |
| </step> |
| <step> |
| <para>Configure Guacamole to use TOTP authentication, as described below.</para> |
| </step> |
| </procedure> |
| <important> |
| <para>You will need to restart Guacamole by restarting your servlet container in order |
| to complete the installation. Doing this will disconnect all active users, so be |
| sure that it is safe to do so prior to attempting installation. If you do not |
| configure the TOTP authentication properly, Guacamole will not start up again until |
| the configuration is fixed.</para> |
| </important> |
| <section xml:id="guac-totp-config"> |
| <title>Configuring Guacamole for TOTP</title> |
| <indexterm> |
| <primary>configuring TOTP</primary> |
| </indexterm> |
| <indexterm> |
| <primary>TOTP</primary> |
| <secondary>configuration</secondary> |
| </indexterm> |
| <para>With the exception of <link linkend="totp-prerequisites">the storage and |
| permission requirements described above</link>, the TOTP extension should work |
| out-of-the-box without any additional configuration. Defaults have been chosen for |
| all configuration parameters such that the TOTP extension will be compatible with |
| Google Authenticator and similar, popular TOTP implementations.</para> |
| <para>If your intended authentication application or device has different requirements, |
| or you wish to override the defaults, additional properties may be specified within |
| <filename>guacamole.properties</filename>:</para> |
| <variablelist> |
| <varlistentry> |
| <term><property>totp-issuer</property></term> |
| <listitem> |
| <para>The human-readable name of the entity issuing user accounts. If not |
| specified, "Apache Guacamole" will be used by default.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>totp-digits</property></term> |
| <listitem> |
| <para>The number of digits which should be included in each generated TOTP |
| code. Legal values are 6, 7, or 8. By default, 6-digit codes are |
| generated.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>totp-period</property></term> |
| <listitem> |
| <para>The duration that each generated code should remain valid, in seconds. |
| By default, each code remains valid for 30 seconds.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>totp-mode</property></term> |
| <listitem> |
| <para>The hash algorithm that should be used to generate TOTP codes. Legal |
| values are "sha1", "sha256", and "sha512". By default, "sha1" is |
| used.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </section> |
| <section xml:id="completing-totp-install"> |
| <title>Completing the installation</title> |
| <para>Guacamole will only reread <filename>guacamole.properties</filename> and load |
| newly-installed extensions during startup, so your servlet container will need to be |
| restarted before TOTP authentication will take effect. Restart your servlet |
| container and give the new authentication a try.</para> |
| <para> |
| <important> |
| <para>You only need to restart your servlet container. <emphasis>You do not need |
| to restart <package>guacd</package></emphasis>.</para> |
| <para><package>guacd</package> is completely independent of the web application |
| and does not deal with <filename>guacamole.properties</filename> or the |
| authentication system in any way. Since you are already restarting the |
| servlet container, restarting <package>guacd</package> as well technically |
| won't hurt anything, but doing so is completely pointless.</para> |
| </important> |
| </para> |
| <para>If Guacamole does not come back online after restarting your servlet container, |
| check the logs. Problems in the configuration of the TOTP extension may prevent |
| Guacamole from starting up, and any such errors will be recorded in the logs of your |
| servlet container.</para> |
| </section> |
| </section> |
| </chapter> |