| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 9. TOTP two-factor authentication</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="duo-auth.html" title="Chapter 8. Duo two-factor authentication" /><link rel="next" href="header-auth.html" title="Chapter 10. HTTP header authentication" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> |
| </head><body> |
| <!-- CONTENT --> |
| |
| <div id="page"><div id="content"> |
| <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. TOTP two-factor authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="duo-auth.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="header-auth.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="totp-auth"></a>Chapter 9. TOTP two-factor authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="totp-auth.html#totp-prerequisites">Prerequisites</a></span></dt><dt><span class="section"><a href="totp-auth.html#totp-architecture">How TOTP works with Guacamole</a></span></dt><dd><dl><dt><span class="section"><a href="totp-auth.html#totp-enrollment">Enrollment</a></span></dt></dl></dd><dt><span class="section"><a href="totp-auth.html#totp-downloading">Downloading the TOTP extension</a></span></dt><dt><span class="section"><a href="totp-auth.html#installing-totp-auth">Installing TOTP authentication</a></span></dt><dd><dl><dt><span class="section"><a href="totp-auth.html#guac-totp-config">Configuring Guacamole for TOTP</a></span></dt><dt><span class="section"><a href="totp-auth.html#completing-totp-install">Completing the installation</a></span></dt></dl></dd></dl></div><a id="idm46420857820416" class="indexterm"></a><p>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 |
| <a class="link" href="totp-auth.html#totp-prerequisites" title="Prerequisites">base requirements for key storage and |
| enrollment</a> are met. The TOTP authentication extension allows users to be |
| additionally verified against a user-specific and secret key generated during <a class="link" href="totp-auth.html#totp-enrollment" title="Enrollment">enrollment of their authentication device</a>.</p><div class="important"><h3 class="title">Important</h3><p>This chapter involves modifying the contents of <code class="varname">GUACAMOLE_HOME</code> - |
| the Guacamole configuration directory. If you are unsure where |
| <code class="varname">GUACAMOLE_HOME</code> is located on your system, please consult <a class="xref" href="configuring-guacamole.html" title="Chapter 5. Configuring Guacamole">Chapter 5, <em>Configuring Guacamole</em></a> before proceeding.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="totp-prerequisites"></a>Prerequisites</h2></div></div></div><p>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:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Another extension must be installed which supports storage of arbitrary data |
| from other extensions. <span class="emphasis"><em>Currently the only extensions provided with |
| Guacamole which support this kind of storage are the <a class="link" href="jdbc-auth.html" title="Chapter 6. Database authentication">database authentication |
| extensions</a>.</em></span></p></li><li class="listitem"><p>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 <a class="link" href="administration.html#user-management" title="User management">administrative web interface</a> with a |
| checkbox labeled "change own password". <span class="emphasis"><em>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.</em></span></p></li></ul></div><p>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 <a class="xref" href="jdbc-auth.html" title="Chapter 6. Database authentication">Chapter 6, <em>Database authentication</em></a>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="totp-architecture"></a>How TOTP works with Guacamole</h2></div></div></div><p>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:</p><div class="informalfigure"><div class="mediaobject"><img src="images/totp-auth-factor-1.png" width="180" /></div></div><p>Only after authentication has succeeded with one of those methods will Guacamole |
| prompt the user to further verify their identity with an authentication code:</p><div class="informalfigure"><div class="mediaobject"><img src="images/totp-auth-factor-2.png" width="360" /></div></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="totp-enrollment"></a>Enrollment</h3></div></div></div><p>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:</p><div class="mediaobject"><img src="images/totp-enroll.png" width="360" /></div><p>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:</p><div class="mediaobject"><img src="images/totp-enroll-detail.png" width="360" /></div><p>Enrollment is completed once the user enters a valid authentication code generated |
| by their device using the provided key.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="totp-downloading"></a>Downloading the TOTP extension</h2></div></div></div><p>The TOTP authentication extension is available separately from the main |
| <code class="filename">guacamole.war</code>. 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: <a class="link" href="http://guacamole.apache.org/releases/" target="_top">http://guacamole.apache.org/releases/</a>.</p><p>The TOTP authentication extension is packaged as a <code class="filename">.tar.gz</code> file |
| containing only the extension itself, |
| <code class="filename">guacamole-auth-totp-1.1.0.jar</code>, which must ultimately be placed in |
| <code class="filename">GUACAMOLE_HOME/extensions</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing-totp-auth"></a>Installing TOTP authentication</h2></div></div></div><p>Guacamole extensions are self-contained <code class="filename">.jar</code> files which are |
| located within the <code class="filename">GUACAMOLE_HOME/extensions</code> directory. To install |
| the TOTP authentication extension, you must:</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Create the <code class="filename">GUACAMOLE_HOME/extensions</code> directory, if it |
| does not already exist.</p></li><li class="step"><p>Copy <code class="filename">guacamole-auth-totp-1.1.0.jar</code> within |
| <code class="filename">GUACAMOLE_HOME/extensions</code>.</p></li><li class="step"><p>Configure Guacamole to use TOTP authentication, as described below.</p></li></ol></div><div class="important"><h3 class="title">Important</h3><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guac-totp-config"></a>Configuring Guacamole for TOTP</h3></div></div></div><a id="idm46420848413344" class="indexterm"></a><a id="idm46420848412448" class="indexterm"></a><p>With the exception of <a class="link" href="totp-auth.html#totp-prerequisites" title="Prerequisites">the storage and |
| permission requirements described above</a>, 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.</p><p>If your intended authentication application or device has different requirements, |
| or you wish to override the defaults, additional properties may be specified within |
| <code class="filename">guacamole.properties</code>:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">totp-issuer</span></span></dt><dd><p>The human-readable name of the entity issuing user accounts. If not |
| specified, "Apache Guacamole" will be used by default.</p></dd><dt><span class="term"><span class="property">totp-digits</span></span></dt><dd><p>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.</p></dd><dt><span class="term"><span class="property">totp-period</span></span></dt><dd><p>The duration that each generated code should remain valid, in seconds. |
| By default, each code remains valid for 30 seconds.</p></dd><dt><span class="term"><span class="property">totp-mode</span></span></dt><dd><p>The hash algorithm that should be used to generate TOTP codes. Legal |
| values are "sha1", "sha256", and "sha512". By default, "sha1" is |
| used.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="completing-totp-install"></a>Completing the installation</h3></div></div></div><p>Guacamole will only reread <code class="filename">guacamole.properties</code> 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.</p><p> |
| </p><div class="important"><h3 class="title">Important</h3><p>You only need to restart your servlet container. <span class="emphasis"><em>You do not need |
| to restart <span class="package">guacd</span></em></span>.</p><p><span class="package">guacd</span> is completely independent of the web application |
| and does not deal with <code class="filename">guacamole.properties</code> or the |
| authentication system in any way. Since you are already restarting the |
| servlet container, restarting <span class="package">guacd</span> as well technically |
| won't hurt anything, but doing so is completely pointless.</p></div><p> |
| </p><p>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.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="duo-auth.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="header-auth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 8. Duo two-factor authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 10. HTTP header authentication</td></tr></table></div> |
| |
| </div></div> |
| </body></html> |
