doc/1.4.0/gug/header-auth.html (209 lines of code) (raw):
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>HTTP header authentication — Apache Guacamole Manual v1.4.0</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/tabs.css" type="text/css" />
<link rel="stylesheet" href="_static/gug.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/tabs.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Encrypted JSON authentication" href="json-auth.html" />
<link rel="prev" title="TOTP two-factor authentication" href="totp-auth.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home"> Apache Guacamole
</a>
<div class="version">
1.4.0
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption" role="heading"><span class="caption-text">Overview</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">User's Guide</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="guacamole-architecture.html">Implementation and architecture</a></li>
<li class="toctree-l1"><a class="reference internal" href="installing-guacamole.html">Installing Guacamole natively</a></li>
<li class="toctree-l1"><a class="reference internal" href="guacamole-docker.html">Installing Guacamole with Docker</a></li>
<li class="toctree-l1"><a class="reference internal" href="reverse-proxy.html">Proxying Guacamole</a></li>
<li class="toctree-l1"><a class="reference internal" href="configuring-guacamole.html">Configuring Guacamole</a></li>
<li class="toctree-l1"><a class="reference internal" href="jdbc-auth.html">Database authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="ldap-auth.html">LDAP authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="duo-auth.html">Duo two-factor authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="totp-auth.html">TOTP two-factor authentication</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">HTTP header authentication</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#downloading-the-http-header-authentication-extension">Downloading the HTTP header authentication extension</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installing-http-header-authentication">Installing HTTP header authentication</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#configuring-guacamole-for-http-header-authentication">Configuring Guacamole for HTTP header authentication</a></li>
<li class="toctree-l3"><a class="reference internal" href="#completing-the-installation">Completing the installation</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="json-auth.html">Encrypted JSON authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="cas-auth.html">CAS Authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="openid-auth.html">OpenID Connect Authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="saml-auth.html">SAML Authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="radius-auth.html">RADIUS Authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="adhoc-connections.html">Ad-hoc Connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="using-guacamole.html">Using Guacamole</a></li>
<li class="toctree-l1"><a class="reference internal" href="administration.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Developer's Guide</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="guacamole-protocol.html">The Guacamole protocol</a></li>
<li class="toctree-l1"><a class="reference internal" href="libguac.html">libguac</a></li>
<li class="toctree-l1"><a class="reference internal" href="guacamole-common.html">guacamole-common</a></li>
<li class="toctree-l1"><a class="reference internal" href="guacamole-common-js.html">guacamole-common-js</a></li>
<li class="toctree-l1"><a class="reference internal" href="guacamole-ext.html">guacamole-ext</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom-protocols.html">Adding new protocols</a></li>
<li class="toctree-l1"><a class="reference internal" href="custom-auth.html">Custom authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="event-listeners.html">Event listeners</a></li>
<li class="toctree-l1"><a class="reference internal" href="writing-you-own-guacamole-app.html">Writing your own Guacamole application</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Appendices</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="protocol-reference.html">Guacamole protocol reference</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Apache Guacamole</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home"></a> »</li>
<li>HTTP header authentication</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/header-auth.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="http-header-authentication">
<h1>HTTP header authentication<a class="headerlink" href="#http-header-authentication" title="Permalink to this headline">¶</a></h1>
<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="admonition important">
<p class="admonition-title">Important</p>
<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. <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></p>
</div>
<div class="section" id="downloading-the-http-header-authentication-extension">
<span id="header-downloading"></span><h2>Downloading the HTTP header authentication extension<a class="headerlink" href="#downloading-the-http-header-authentication-extension" title="Permalink to this headline">¶</a></h2>
<p>The HTTP header authentication extension is available separately from the main
<code class="docutils literal notranslate"><span class="pre">guacamole.war</span></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="reference external" href="http://guacamole.apache.org/releases/">http://guacamole.apache.org/releases/</a>.</p>
<p>The HTTP header authentication extension is packaged as a <code class="docutils literal notranslate"><span class="pre">.tar.gz</span></code> file
containing only the extension itself, <code class="docutils literal notranslate"><span class="pre">guacamole-auth-header-1.4.0.jar</span></code>, which
must ultimately be placed in <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code>.</p>
</div>
<div class="section" id="installing-http-header-authentication">
<span id="installing-header-auth"></span><h2>Installing HTTP header authentication<a class="headerlink" href="#installing-http-header-authentication" title="Permalink to this headline">¶</a></h2>
<p>Guacamole extensions are self-contained <code class="docutils literal notranslate"><span class="pre">.jar</span></code> files which are located within
the <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code> directory. <em>If you are unsure where
<code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME</span></code> is located on your system, please consult
<a class="reference internal" href="configuring-guacamole.html"><span class="doc std std-doc">Configuring Guacamole</span></a> before proceeding.</em></p>
<p>To install the HTTP header authentication extension, you must:</p>
<ol class="simple">
<li><p>Create the <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code> directory, if it does not already
exist.</p></li>
<li><p>Copy <code class="docutils literal notranslate"><span class="pre">guacamole-auth-header-1.4.0.jar</span></code> within <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code>.</p></li>
<li><p>Configure Guacamole to use HTTP header authentication, as described below.</p></li>
</ol>
<div class="section" id="configuring-guacamole-for-http-header-authentication">
<span id="guac-header-config"></span><h3>Configuring Guacamole for HTTP header authentication<a class="headerlink" href="#configuring-guacamole-for-http-header-authentication" title="Permalink to this headline">¶</a></h3>
<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="docutils literal notranslate"><span class="pre">REMOTE_USER</span></code> header, if present. If your
authentication system uses a different HTTP header, you will need to override
this by specifying the <code class="docutils literal notranslate"><span class="pre">http-auth-header</span></code> property within
<a class="reference internal" href="configuring-guacamole.html#initial-setup"><span class="std std-ref"><code class="docutils literal notranslate"><span class="pre">guacamole.properties</span></code></span></a>:</p>
<dl class="simple myst">
<dt><code class="docutils literal notranslate"><span class="pre">http-auth-header</span></code></dt><dd><p>The HTTP header containing the username of the authenticated user. This
property is optional. If not specified, <code class="docutils literal notranslate"><span class="pre">REMOTE_USER</span></code> will be used by
default.</p>
</dd>
</dl>
</div>
<div class="section" id="completing-the-installation">
<span id="completing-header-install"></span><h3>Completing the installation<a class="headerlink" href="#completing-the-installation" title="Permalink to this headline">¶</a></h3>
<p>Guacamole will only reread <code class="docutils literal notranslate"><span class="pre">guacamole.properties</span></code> and load newly-installed
extensions during startup, so your servlet container will need to be restarted
before HTTP header authentication can be used. <em>Doing this will disconnect all
active users, so be sure that it is safe to do so prior to attempting
installation.</em> When ready, restart your servlet container and give the new
authentication a try.</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="json-auth.html" class="btn btn-neutral float-right" title="Encrypted JSON authentication" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
<a href="totp-auth.html" class="btn btn-neutral float-left" title="TOTP two-factor authentication" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>Copyright © 2021 <a href="http://www.apache.org/">The Apache Software Foundation</a>,
Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are
trademarks of The Apache Software Foundation.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>