doc/gug/header-auth.html

<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>HTTP header authentication — Apache Guacamole Manual v1.5.5</title> <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" />  <script src="_static/jquery.js?v=5d32c60e"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="_static/documentation_options.js?v=5929fcd5"></script> <script src="_static/doctools.js?v=888ff710"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script> <script src="_static/tabs.js?v=3ee01567"></script> <script 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.5.5 </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" aria-label="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="Navigation menu"> <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="vault.html">Retrieving secrets from a vault</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="recording-playback.html">Viewing session recordings in-browser</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="Mobile navigation menu" > <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="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item active">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"> <section id="http-header-authentication"> <h1>HTTP header authentication<a class="headerlink" href="#http-header-authentication" title="Link to this heading"></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> <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="Link to this heading"></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.5.5.jar</span></code>, which must ultimately be placed in <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code>.</p> </section> <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="Link to this heading"></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="arabic 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.5.5.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> <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="Link to this heading"></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> </section> <section id="completing-the-installation"> <span id="completing-header-install"></span><h3>Completing the installation<a class="headerlink" href="#completing-the-installation" title="Link to this heading"></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> </section> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <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> <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> </div> <hr/> <div role="contentinfo"> <p>Copyright © 2024 <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> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>

doc/gug/header-auth.html (207 lines of code) (raw):