guacamole-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [1/3] incubator-guacamole-manual git commit: GUACAMOLE-136: Document use of the Duo multi-factor authentication extension.
Date Sat, 21 Jan 2017 20:16:48 GMT
Repository: incubator-guacamole-manual
Updated Branches:
  refs/heads/master 3ef53a014 -> b2c261add

GUACAMOLE-136: Document use of the Duo multi-factor authentication extension.


Branch: refs/heads/master
Commit: b6c9c437930560d99791ff5efe14cf5cedab1064
Parents: d1a691d
Author: Michael Jumper <>
Authored: Thu Jan 19 23:44:52 2017 -0800
Committer: Michael Jumper <>
Committed: Fri Jan 20 11:44:17 2017 -0800

 src/chapters/duo-auth.xml                    | 228 ++++++++++++++++++++++
 src/chapters/images/duo-add-guacamole.png    | Bin 0 -> 6788 bytes
 src/chapters/images/duo-auth-factor-1.png    | Bin 0 -> 12418 bytes
 src/chapters/images/duo-auth-factor-2.png    | Bin 0 -> 28876 bytes
 src/chapters/images/duo-copy-details.png     | Bin 0 -> 19979 bytes
 src/chapters/images/duo-rename-guacamole.png | Bin 0 -> 13827 bytes
 src/gug.xml                                  |   1 +
 7 files changed, 229 insertions(+)
diff --git a/src/chapters/duo-auth.xml b/src/chapters/duo-auth.xml
new file mode 100644
index 0000000..11d3870
--- /dev/null
+++ b/src/chapters/duo-auth.xml
@@ -0,0 +1,228 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xml:id="duo-auth" xmlns="" version="5.0" xml:lang="en"
+    xmlns:xi="" xmlns:xlink="">
+    <title>Duo two-factor authentication</title>
+    <indexterm>
+        <primary>Duo</primary>
+    </indexterm>
+    <para>Guacamole supports Duo as a second authentication factor, layered on top
of any other
+        authentication extension, including those available from the main project website.
The Duo
+        authentication extension allows users to be additionally verified against the Duo
+        before the authentication process is allowed to succeed.</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="duo-architecture">
+        <title>How Duo works with Guacamole</title>
+        <para>Guacamole provides support for Duo as a second authentication factor.
To make use of
+            the Duo authentication extension, some other authentication mechanism will need
+            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/duo-auth-factor-1.png" format="PNG"
+                        contentwidth="2in"/>
+                </imageobject>
+            </mediaobject>
+        </informalfigure>
+        <para>Only after authentication has succeeded with one of those methods will
Guacamole reach
+            out to Duo to obtain additional verification of user identity:</para>
+        <informalfigure>
+            <mediaobject>
+                <imageobject>
+                    <imagedata fileref="images/duo-auth-factor-2.png" format="PNG"
+                        contentwidth="4in"/>
+                </imageobject>
+            </mediaobject>
+        </informalfigure>
+        <para>If both the initial authentication attempt and verification through Duo
succeed, the
+            user will be allowed in. If either mechanism fails, access to Guacamole is
+            denied.</para>
+    </section>
+    <section xml:id="duo-downloading">
+        <title>Downloading the Duo extension</title>
+        <para>The Duo authentication extension is available separately from the main
+                <filename>guacamole.war</filename>. The link for this and all
+            officially-supported and compatible extensions for a particular version of Guacamole
+            provided on the release notes for that version. You can find the release notes
+            current versions of Guacamole here: <link
+                xlink:href=""
+                ></link>.</para>
+        <para>The Duo authentication extension is packaged as a <filename>.tar.gz</filename>
+            containing only the extension itself,
+                <filename>guacamole-auth-duo-0.9.11-incubating.jar</filename>,
which must ultimately
+            be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+    </section>
+    <section xml:id="installing-duo-auth">
+        <title>Installing Duo 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 Duo 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-duo-0.9.11-incubating.jar</filename>
+                        <filename>GUACAMOLE_HOME/extensions</filename>.</para>
+            </step>
+            <step>
+                <para>Configure Guacamole to use Duo 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
+                configure the Duo authentication properly, Guacamole will not start up again
+                the configuration is fixed.</para>
+        </important>
+        <section>
+            <title xml:id="duo-guac-config">Adding Guacamole to Duo</title>
+            <para>Duo does not provide a specific integration option for Guacamole,
but Guacamole's
+                Duo extension uses Duo's generic authentication API. To use Guacamole with
Duo, you
+                will need to add it as a new "Auth API" application from within the "Applications"
+                tab of the admin panel of your Duo account:</para>
+            <informalfigure>
+                <mediaobject>
+                    <imageobject>
+                        <imagedata fileref="images/duo-add-guacamole.png" format="PNG"
+                            contentwidth="6in"/>
+                    </imageobject>
+                </mediaobject>
+            </informalfigure>
+            <para>Within the settings of the newly-added application, rename the application
+                something more representative than "Auth API". This application name is what
will be
+                presented to your users when they are prompted by Duo for additional
+                authentication:</para>
+            <informalfigure>
+                <mediaobject>
+                    <imageobject>
+                        <imagedata fileref="images/duo-rename-guacamole.png" format="PNG"
+                            contentwidth="6in"/>
+                    </imageobject>
+                </mediaobject>
+            </informalfigure>
+            <para>Once you've finished adding Guacamole as an "Auth API" application,
+                configuration information required to configure Guacamole is listed within
+                application's "Details" section. You will need to copy the integration key,
+                key, and API hostname - they will later be specified within
+                    <filename></filename>:</para>
+            <informalfigure>
+                <mediaobject>
+                    <imageobject>
+                        <imagedata fileref="images/duo-copy-details.png" format="PNG"
+                            contentwidth="6in"/>
+                    </imageobject>
+                </mediaobject>
+            </informalfigure>
+        </section>
+        <section xml:id="guac-duo-config">
+            <title>Configuring Guacamole for Duo</title>
+            <indexterm>
+                <primary>configuring Duo</primary>
+            </indexterm>
+            <indexterm>
+                <primary>Duo</primary>
+                <secondary>configuration</secondary>
+            </indexterm>
+            <para>The application-specific configuration information retrieved from
Duo must be
+                added to <filename></filename> to describe
how Guacamole should
+                connect to the Duo service:</para>
+            <variablelist>
+                <varlistentry>
+                    <term><property>duo-api-hostname</property></term>
+                    <listitem>
+                        <para>The hostname of the Duo API endpoint to be used to verify
+                            identities. This will usually be in the form
+                                    "<uri>api-<replaceable>XXXXXXXX</replaceable></uri>",
+                            where "<replaceable>XXXXXXXX</replaceable>" is some
+                            alphanumeric value assigned by Duo. This value will have been
+                            by Duo when you added Guacamole as an "Auth API" application,
and can be
+                            found within the application details in the "API hostname" field.
+                                <emphasis>This value is required.</emphasis></para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><property>duo-integration-key</property></term>
+                    <listitem>
+                        <para>The integration key provided for Guacamole by Duo. This
value will
+                            have been generated by Duo when you added Guacamole as an "Auth
+                            application, and can be found within the application details
in the
+                            "Integration key" field. <emphasis>This value is required
and must be
+                                EXACTLY 20 characters.</emphasis></para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><property>duo-secret-key</property></term>
+                    <listitem>
+                        <para>The secret key provided for Guacamole by Duo. This value
will have
+                            been generated by Duo when you added Guacamole as an "Auth API"
+                            application, and can be found within the application details
in the
+                            "Secret key" field. <emphasis>This value is required and
must be EXACTLY
+                                20 characters.</emphasis></para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+            <para>In addition to the above, <emphasis>you must also manually
generate an
+                    "application key"</emphasis>. The application key is required by
+                authentication API, but is not provided by Duo. It is an arbitrary value
meant to be
+                unique to each deployment of an application using their API.</para>
+            <variablelist>
+                <varlistentry>
+                    <term><property>duo-application-key</property></term>
+                    <listitem>
+                        <para>An arbitrary, random key which you manually generated
for Guacamole.
+                                <emphasis>This value is required and must be AT LEAST
+                                characters.</emphasis></para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+            <para>The application key can be generated with any method as long as it
is sufficiently
+                random. There exist utilities which will do this for you, like
+                    <command>pwgen</command>:</para>
+            <informalexample>
+                <screen><prompt>$</prompt> <userinput>pwgen 40 1</userinput>
+            </informalexample>
+            <para>Alternatively, one quick and fairly portable way to do this is to
use the
+                    <command>dd</command> utility to copy random bytes from the
secure random device
+                    <filename>/dev/random</filename>, sending the data through
a cryptographic hash
+                tool with a sufficiently-long result, like <command>sha256sum</command>:</para>
+            <informalexample>
+                <screen><prompt>$</prompt> <userinput>dd if=/dev/random
count=1 | sha256sum</userinput>
+<computeroutput>5d16d6bb86da73e7d1abd3286b21dcf3b3e707532e64ceebc7a008350d0d485d -</computeroutput>
+            </informalexample>
+        </section>
+        <section xml:id="completing-duo-install">
+            <title>Completing the installation</title>
+            <para>Guacamole will only reread <filename></filename>
and load
+                newly-installed extensions during startup, so your servlet container will
need to be
+                restarted before Duo authentication will take effect. Restart your servlet
+                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></filename>
or the
+                        authentication system in any way. Since you are already restarting
+                        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
+                check the logs. Problems in the configuration of the Duo extension may prevent
+                Guacamole from starting up, and any such errors will be recorded in the logs
of your
+                servlet container.</para>
+        </section>
+    </section>
diff --git a/src/chapters/images/duo-add-guacamole.png b/src/chapters/images/duo-add-guacamole.png
new file mode 100644
index 0000000..82ab175
Binary files /dev/null and b/src/chapters/images/duo-add-guacamole.png differ
diff --git a/src/chapters/images/duo-auth-factor-1.png b/src/chapters/images/duo-auth-factor-1.png
new file mode 100644
index 0000000..3a82976
Binary files /dev/null and b/src/chapters/images/duo-auth-factor-1.png differ
diff --git a/src/chapters/images/duo-auth-factor-2.png b/src/chapters/images/duo-auth-factor-2.png
new file mode 100644
index 0000000..8c35648
Binary files /dev/null and b/src/chapters/images/duo-auth-factor-2.png differ
diff --git a/src/chapters/images/duo-copy-details.png b/src/chapters/images/duo-copy-details.png
new file mode 100644
index 0000000..d7faa7a
Binary files /dev/null and b/src/chapters/images/duo-copy-details.png differ
diff --git a/src/chapters/images/duo-rename-guacamole.png b/src/chapters/images/duo-rename-guacamole.png
new file mode 100644
index 0000000..85412d7
Binary files /dev/null and b/src/chapters/images/duo-rename-guacamole.png differ
diff --git a/src/gug.xml b/src/gug.xml
index 222ece3..cc84bec 100644
--- a/src/gug.xml
+++ b/src/gug.xml
@@ -160,6 +160,7 @@
         <xi:include href="chapters/configuring.xml"/>
         <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/noauth.xml"/>
         <xi:include href="chapters/using.xml"/>
         <xi:include href="chapters/administration.xml"/>

View raw message