| <?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 10. HTTP header 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="totp-auth.html" title="Chapter 9. TOTP two-factor authentication" /><link rel="next" href="cas-auth.html" title="Chapter 11. CAS 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 10. HTTP header authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="totp-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="cas-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="header-auth"></a>Chapter 10. HTTP header authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="header-auth.html#header-downloading">Downloading the HTTP header authentication extension</a></span></dt><dt><span class="section"><a href="header-auth.html#installing-header-auth">Installing HTTP header authentication</a></span></dt><dd><dl><dt><span class="section"><a href="header-auth.html#guac-header-config">Configuring Guacamole for HTTP header authentication</a></span></dt><dt><span class="section"><a href="header-auth.html#completing-header-install">Completing the installation</a></span></dt></dl></dd></dl></div><a id="idm46420849422992" class="indexterm"></a><p>Guacamole supports delegating authentication to an arbitrary external service, relying on |
| the presence of an HTTP header which contains the username of the authenticated user. This |
| authentication method must be layered on top of some other authentication extension, such as |
| those available from the main project website, in order to provide access to actual |
| connections.</p><div class="important"><h3 class="title">Important</h3><p>All external requests must be properly sanitized if this extension is used. The chosen |
| HTTP header must be stripped from untrusted requests, such that the authentication |
| service is the only possible source of that header. <span class="emphasis"><em>If such sanitization is |
| not performed, it will be trivial for malicious users to add this header manually, |
| and thus gain unrestricted access.</em></span></p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="header-downloading"></a>Downloading the HTTP header authentication extension</h2></div></div></div><p>The HTTP header 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 HTTP header authentication extension is packaged as a <code class="filename">.tar.gz</code> |
| file containing only the extension itself, |
| <code class="filename">guacamole-auth-header-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-header-auth"></a>Installing HTTP header 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. |
| <span class="emphasis"><em>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.</em></span></p><p>To install the HTTP header 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-header-1.1.0.jar</code> within |
| <code class="filename">GUACAMOLE_HOME/extensions</code>.</p></li><li class="step"><p>Configure Guacamole to use HTTP header authentication, as described |
| below.</p></li></ol></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guac-header-config"></a>Configuring Guacamole for HTTP header authentication</h3></div></div></div><a id="idm46420848418672" class="indexterm"></a><a id="idm46420849597792" class="indexterm"></a><p>The HTTP header authentication extension provides only one configuration property, |
| and it is optional. By default, the extension will pull the username of the |
| authenticated user from the <code class="constant">REMOTE_USER</code> header, if present. If |
| your authentication system uses a different HTTP header, you will need to override |
| this by specifying the <span class="property">http-auth-header</span> property within <a class="link" href="configuring-guacamole.html#initial-setup" title="guacamole.properties"><code class="filename">guacamole.properties</code></a>:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">http-auth-header</span></span></dt><dd><p>The HTTP header containing the username of the authenticated user. |
| This property is optional. If not specified, |
| <code class="constant">REMOTE_USER</code> will be used by default.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="completing-header-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 HTTP header authentication can be used. <span class="emphasis"><em>Doing this will |
| disconnect all active users, so be sure that it is safe to do so prior to |
| attempting installation.</em></span> When ready, restart your servlet container |
| and give the new authentication a try.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="totp-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="cas-auth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. TOTP 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 11. CAS Authentication</td></tr></table></div> |
| |
| </div></div> |
| </body></html> |
