src/chapters/totp-auth.xml - guacamole-manual - Git at Google

 <?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 will 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>
	<?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 will 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>