You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by vn...@apache.org on 2018/10/14 21:22:59 UTC
[1/2] guacamole-manual git commit: GUACAMOLE-96: Document support for
multi-factor authentication using TOTP.
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 <mj...@apache.org>
Authored: Thu Oct 11 01:36:31 2018 -0700
Committer: Michael Jumper <mj...@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"/>
[2/2] guacamole-manual git commit: GUACAMOLE-96: Merge document
support for multi-factor authentication using TOTP.
Posted by vn...@apache.org.
GUACAMOLE-96: Merge 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/949f9c75
Tree: http://git-wip-us.apache.org/repos/asf/guacamole-manual/tree/949f9c75
Diff: http://git-wip-us.apache.org/repos/asf/guacamole-manual/diff/949f9c75
Branch: refs/heads/staging/1.0.0
Commit: 949f9c75e86c7e8933c074b7fd85dec2452edd03
Parents: 7083723 f1d368b
Author: Nick Couchman <vn...@apache.org>
Authored: Sun Oct 14 17:20:56 2018 -0400
Committer: Nick Couchman <vn...@apache.org>
Committed: Sun Oct 14 17:20:56 2018 -0400
----------------------------------------------------------------------
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(+)
----------------------------------------------------------------------