Repository: guacamole-manual Updated Branches: refs/heads/staging/1.0.0 708372381 -> 949f9c75e
GUACAMOLE-96: Document support for multi-factor authentication using TOTP. Project: http://git-wip-us.apache.org/repos/asf/guacamole-manual/repo Commit: http://git-wip-us.apache.org/repos/asf/guacamole-manual/commit/f1d368be Tree: http://git-wip-us.apache.org/repos/asf/guacamole-manual/tree/f1d368be Diff: http://git-wip-us.apache.org/repos/asf/guacamole-manual/diff/f1d368be Branch: refs/heads/staging/1.0.0 Commit: f1d368be9b3787f42209a4ee8cede7bf99153270 Parents: 7083723 Author: Michael Jumper <mjum...@apache.org> Authored: Thu Oct 11 01:36:31 2018 -0700 Committer: Michael Jumper <mjum...@apache.org> Committed: Thu Oct 11 01:46:05 2018 -0700 ---------------------------------------------------------------------- src/chapters/images/totp-auth-factor-1.png | Bin 0 -> 12418 bytes src/chapters/images/totp-auth-factor-2.png | Bin 0 -> 14088 bytes src/chapters/images/totp-enroll-detail.png | Bin 0 -> 42801 bytes src/chapters/images/totp-enroll.png | Bin 0 -> 33722 bytes src/chapters/totp-auth.xml | 214 ++++++++++++++++++++++++ src/gug.xml | 1 + 6 files changed, 215 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/f1d368be/src/chapters/images/totp-auth-factor-1.png ---------------------------------------------------------------------- diff --git a/src/chapters/images/totp-auth-factor-1.png b/src/chapters/images/totp-auth-factor-1.png new file mode 100644 index 0000000..3a82976 Binary files /dev/null and b/src/chapters/images/totp-auth-factor-1.png differ http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/f1d368be/src/chapters/images/totp-auth-factor-2.png ---------------------------------------------------------------------- diff --git a/src/chapters/images/totp-auth-factor-2.png b/src/chapters/images/totp-auth-factor-2.png new file mode 100644 index 0000000..c2a649f Binary files /dev/null and b/src/chapters/images/totp-auth-factor-2.png differ http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/f1d368be/src/chapters/images/totp-enroll-detail.png ---------------------------------------------------------------------- diff --git a/src/chapters/images/totp-enroll-detail.png b/src/chapters/images/totp-enroll-detail.png new file mode 100644 index 0000000..afde141 Binary files /dev/null and b/src/chapters/images/totp-enroll-detail.png differ http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/f1d368be/src/chapters/images/totp-enroll.png ---------------------------------------------------------------------- diff --git a/src/chapters/images/totp-enroll.png b/src/chapters/images/totp-enroll.png new file mode 100644 index 0000000..97474b6 Binary files /dev/null and b/src/chapters/images/totp-enroll.png differ http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/f1d368be/src/chapters/totp-auth.xml ---------------------------------------------------------------------- diff --git a/src/chapters/totp-auth.xml b/src/chapters/totp-auth.xml new file mode 100644 index 0000000..4d85c66 --- /dev/null +++ b/src/chapters/totp-auth.xml @@ -0,0 +1,214 @@ +<?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.0.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.0.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> http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/f1d368be/src/gug.xml ---------------------------------------------------------------------- diff --git a/src/gug.xml b/src/gug.xml index 424df7b..df0f66e 100644 --- a/src/gug.xml +++ b/src/gug.xml @@ -161,6 +161,7 @@ <xi:include href="chapters/jdbc-auth.xml"/> <xi:include href="chapters/ldap-auth.xml"/> <xi:include href="chapters/duo-auth.xml"/> + <xi:include href="chapters/totp-auth.xml"/> <xi:include href="chapters/header-auth.xml"/> <xi:include href="chapters/cas-auth.xml"/> <xi:include href="chapters/openid-auth.xml"/>