You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by jm...@apache.org on 2017/01/21 20:12:15 UTC
[1/2] incubator-guacamole-manual git commit: GUACAMOLE-136: Document
use of the Duo multi-factor authentication extension.
Repository: incubator-guacamole-manual
Updated Branches:
refs/heads/staging/0.9.11-incbuating [created] 86b40d51a
GUACAMOLE-136: Document use of the Duo multi-factor authentication extension.
Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/commit/b6c9c437
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/b6c9c437
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/b6c9c437
Branch: refs/heads/staging/0.9.11-incbuating
Commit: b6c9c437930560d99791ff5efe14cf5cedab1064
Parents: d1a691d
Author: Michael Jumper <mj...@apache.org>
Authored: Thu Jan 19 23:44:52 2017 -0800
Committer: Michael Jumper <mj...@apache.org>
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(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/b6c9c437/src/chapters/duo-auth.xml
----------------------------------------------------------------------
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="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>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 service
+ 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 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/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 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.incubator.apache.org/releases/"
+ >http://guacamole.incubator.apache.org/releases/</link>.</para>
+ <para>The Duo authentication extension is packaged as a <filename>.tar.gz</filename> file
+ 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> within
+ <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 not
+ configure the Duo authentication properly, Guacamole will not start up again until
+ 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 to
+ 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, the
+ configuration information required to configure Guacamole is listed within the
+ application's "Details" section. You will need to copy the integration key, secret
+ key, and API hostname - they will later be specified within
+ <filename>guacamole.properties</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>guacamole.properties</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 user
+ identities. This will usually be in the form
+ "<uri>api-<replaceable>XXXXXXXX</replaceable>.duosecurity.com</uri>",
+ where "<replaceable>XXXXXXXX</replaceable>" is some arbitrary
+ alphanumeric value assigned 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 "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 API"
+ 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 Duo's
+ 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 40
+ 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>
+<computeroutput>em1io4zievohneeseiwah0zie2raQuoo2ci5oBoo</computeroutput>
+<prompt>$</prompt></screen>
+ </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>
+<prompt>$</prompt></screen>
+ </informalexample>
+ </section>
+ <section xml:id="completing-duo-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 Duo 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 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>
+</chapter>
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/b6c9c437/src/chapters/images/duo-add-guacamole.png
----------------------------------------------------------------------
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
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/b6c9c437/src/chapters/images/duo-auth-factor-1.png
----------------------------------------------------------------------
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
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/b6c9c437/src/chapters/images/duo-auth-factor-2.png
----------------------------------------------------------------------
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
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/b6c9c437/src/chapters/images/duo-copy-details.png
----------------------------------------------------------------------
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
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/b6c9c437/src/chapters/images/duo-rename-guacamole.png
----------------------------------------------------------------------
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
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/b6c9c437/src/gug.xml
----------------------------------------------------------------------
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"/>
[2/2] incubator-guacamole-manual git commit: GUACAMOLE-136: Merge new
Duo MFA documentation.
Posted by jm...@apache.org.
GUACAMOLE-136: Merge new Duo MFA documentation.
Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/commit/86b40d51
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/86b40d51
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/86b40d51
Branch: refs/heads/staging/0.9.11-incbuating
Commit: 86b40d51a88c6bf386a221e848e7951267432bd0
Parents: 3ef53a0 b6c9c43
Author: James Muehlner <ja...@guac-dev.org>
Authored: Sat Jan 21 12:11:17 2017 -0800
Committer: James Muehlner <ja...@guac-dev.org>
Committed: Sat Jan 21 12:11: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(+)
----------------------------------------------------------------------