doc/gug/custom-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>Custom 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="Event listeners" href="event-listeners.html" /> <link rel="prev" title="Adding new protocols" href="custom-protocols.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"> Overview <ul> <li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li> </ul> User's Guide <ul> <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"><a class="reference internal" href="header-auth.html">HTTP header authentication</a></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> Developer's Guide <ul class="current"> <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 current"><a class="current reference internal" href="#">Custom authentication</a><ul> <li class="toctree-l2"><a class="reference internal" href="#guacamoles-authentication-model">Guacamole’s authentication model</a></li> <li class="toctree-l2"><a class="reference internal" href="#a-guacamole-extension-skeleton">A Guacamole extension skeleton</a></li> <li class="toctree-l2"><a class="reference internal" href="#building-the-extension">Building the extension</a></li> <li class="toctree-l2"><a class="reference internal" href="#configuration-and-authentication">Configuration and authentication</a></li> <li class="toctree-l2"><a class="reference internal" href="#parsing-the-configuration">Parsing the configuration</a></li> <li class="toctree-l2"><a class="reference internal" href="#installing-the-extension">Installing the extension</a></li> </ul> </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> Appendices <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" > <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">Custom authentication</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/custom-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="custom-authentication"> <h1>Custom authentication<a class="headerlink" href="#custom-authentication" title="Link to this heading"></a></h1> Guacamole’s authentication layer is designed to be extendable such that users can integrate Guacamole into existing authentication systems without having to resort to writing their own web application around the Guacamole API. The web application comes with a default authentication mechanism which uses an XML file to associate users with connections. Extensions for Guacamole that provide LDAP-based authentication or database-based authentication have also been developed. To demonstrate the principles involved, we will implement a very simple authentication extension which associates a single user/password pair with a single connection, with all this information saved in properties inside the <code class="docutils literal notranslate">guacamole.properties</code> file. In general, all other authentication extensions for Guacamole will use the principles demonstrated here. This tutorial demonstrates the simplest way to create an authentication extension for Guacamole - an authentication extension that does not support management of users and connections via the web interface. <section id="guacamoles-authentication-model"> <h2>Guacamole’s authentication model<a class="headerlink" href="#guacamoles-authentication-model" title="Link to this heading"></a></h2> When you view any page in Guacamole, whether that be the login screen or the client interface, the page makes an authentication attempt with the web application, sending all available credentials. After entering your username and password, the exact same process occurs, except the web application receives the username and password as well. The web application handles this authentication attempt by collecting all credentials available and passing them to designated classes called “authentication providers”. Given the set of credentials, authentication providers return a context object that provides restricted access to other users and connections, if any. </section> <section id="a-guacamole-extension-skeleton"> <h2>A Guacamole extension skeleton<a class="headerlink" href="#a-guacamole-extension-skeleton" title="Link to this heading"></a></h2> For simplicity’s sake, and because this is how things are done upstream in the Guacamole project, we will use Maven to build our extension. The bare minimum required for a Guacamole authentication extension is a <code class="docutils literal notranslate">pom.xml</code> file listing guacamole-ext as a dependency, a single .java file implementing our stub of an authentication provider, and a <code class="docutils literal notranslate">guac-manifest.json</code> file describing the extension and pointing to our authentication provider class. In our stub, we won’t actually do any authentication yet; we’ll just universally reject all authentication attempts by returning <code class="docutils literal notranslate">null</code> for any credentials given. You can verify that this is what happens by checking the server logs. <div class="highlight-xml notranslate"><div class="highlight"><pre><project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>org.apache.guacamole</groupId> <artifactId>guacamole-auth-tutorial</artifactId> <packaging>jar</packaging> <version>1.5.5</version> <name>guacamole-auth-tutorial</name> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> <build> <plugins>  <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.3</version> <configuration> <source>1.8</source> <target>1.8</target> </configuration> </plugin> </plugins> </build> <dependencies>  <dependency> <groupId>org.apache.guacamole</groupId> <artifactId>guacamole-ext</artifactId> <version>1.5.5</version> <scope>provided</scope> </dependency> </dependencies> </project> </pre></div> </div> We won’t need to update this <code class="docutils literal notranslate">pom.xml</code> throughout the rest of the tutorial. Even after adding new files, Maven will just find them and compile as necessary. Naturally, we need the actual authentication extension skeleton code. While you can put this in whatever file and package you want, for the sake of this tutorial, we will assume you are using <code class="docutils literal notranslate">org.apache.guacamole.auth.TutorialAuthenticationProvider</code>. <div class="highlight-java notranslate"><div class="highlight"><pre>package org.apache.guacamole.auth; import java.util.Map; import org.apache.guacamole.GuacamoleException; import org.apache.guacamole.net.auth.simple.SimpleAuthenticationProvider; import org.apache.guacamole.net.auth.Credentials; import org.apache.guacamole.protocol.GuacamoleConfiguration; /** * Authentication provider implementation intended to demonstrate basic use * of Guacamole's extension API. The credentials and connection information for * a single user are stored directly in guacamole.properties. */ public class TutorialAuthenticationProvider extends SimpleAuthenticationProvider { @Override public String getIdentifier() { return "tutorial"; } @Override public Map<String, GuacamoleConfiguration> getAuthorizedConfigurations(Credentials credentials) throws GuacamoleException { // Do nothing ... yet return null; } } </pre></div> </div> To conform with Maven, this skeleton file must be placed within <code class="docutils literal notranslate">src/main/java/org/apache/guacamole/auth</code> as <code class="docutils literal notranslate">TutorialAuthenticationProvider.java</code>. Notice how simple the authentication provider is. The <code class="docutils literal notranslate">SimpleAuthenticationProvider</code> base class simplifies the <code class="docutils literal notranslate">AuthenticationProvider</code> interface, requiring nothing more than a unique identifier (we will use “tutorial”) and a single getAuthorizedConfigurations() implementation, which must return a <code class="docutils literal notranslate">Map</code> of <code class="docutils literal notranslate">GuacamoleConfiguration</code> each associated with some arbitrary unique ID. This unique ID will be presented to the user in the connection list after they log in. For now, <code class="docutils literal notranslate">getAuthorizedConfigurations()</code> will just return <code class="docutils literal notranslate">null</code>. This will cause Guacamole to report an invalid login for every attempt. Note that there is a difference in semantics between returning an empty map and returning <code class="docutils literal notranslate">null</code>, as the former indicates the credentials are authorized but simply have no associated configurations, while the latter indicates the credentials are not authorized at all. The only remaining piece for the overall skeleton to be complete is a <code class="docutils literal notranslate">guac-manifest.json</code> file. This file is absolutely required for all Guacamole extensions. The <code class="docutils literal notranslate">guac-manifest.json</code> format is described in more detail in <a class="reference internal" href="guacamole-ext.html">guacamole-ext</a>. It provides for quite a few properties, but for our authentication extension we are mainly interested in the Guacamole version sanity check (to make sure an extension built for the API of Guacamole version X is not accidentally used against version Y) and telling Guacamole where to find our authentication provider class. The Guacamole extension format requires that <code class="docutils literal notranslate">guac-manifest.json</code> be placed in the root directory of the extension <code class="docutils literal notranslate">.jar</code> file. To accomplish this with Maven, we place it within the <code class="docutils literal notranslate">src/main/resources</code> directory. Maven will automatically pick it up during the build and include it within the <code class="docutils literal notranslate">.jar</code>. <div class="highlight-json notranslate"><div class="highlight"><pre>{ "guacamoleVersion" : "1.5.5", "name" : "Tutorial Authentication Extension", "namespace" : "guac-auth-tutorial", "authProviders" : [ "org.apache.guacamole.auth.TutorialAuthenticationProvider" ] } </pre></div> </div> </section> <section id="building-the-extension"> <h2>Building the extension<a class="headerlink" href="#building-the-extension" title="Link to this heading"></a></h2> Once all three of the above files are in place, the extension will build, and can even be installed within Guacamole (see <a class="reference internal" href="#custom-auth-installing">Installing the extension</a> at the end of this chapter), even though it is just a skeleton at this point. It won’t do anything yet other than reject all authentication attempts, but it’s good to at least try building the extension to make sure nothing is missing and that all steps have been followed correctly so far: <div class="highlight-console notranslate"><div class="highlight"><pre>$ mvn package [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Building guacamole-auth-tutorial 1.5.5 [INFO] ------------------------------------------------------------------------ ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.345 s [INFO] Finished at: 2015-12-16T13:39:00-08:00 [INFO] Final Memory: 14M/138M [INFO] ------------------------------------------------------------------------ $ </pre></div> </div> Assuming you see the “<code class="docutils literal notranslate">BUILD SUCCESS</code>” message when you build the extension, there will be a new file, <code class="docutils literal notranslate">target/guacamole-auth-tutorial-1.5.5.jar</code>, which can be installed within Guacamole and tested. If you changed the name or version of the project in the <code class="docutils literal notranslate">pom.xml</code> file, the name of this new <code class="docutils literal notranslate">.jar</code> file will be different, but it can still be found within <code class="docutils literal notranslate">target/</code>. </section> <section id="configuration-and-authentication"> <h2>Configuration and authentication<a class="headerlink" href="#configuration-and-authentication" title="Link to this heading"></a></h2> Once we receive credentials, we need to validate those credentials against the associated properties in <code class="docutils literal notranslate">guacamole.properties</code> (our source of authentication information for the sake of this tutorial). We will define four properties: <dl class="simple myst"> <dt><code class="docutils literal notranslate">tutorial-user</code></dt><dd>The name of the only user we accept. </dd> <dt><code class="docutils literal notranslate">tutorial-password</code></dt><dd>The password we require for the user specified to be authenticated. </dd> <dt><code class="docutils literal notranslate">tutorial-protocol</code></dt><dd>The protocol of the configuration this user is authorized to use, which will be sent to guacd when the user logs in and selects their connection. </dd> <dt><code class="docutils literal notranslate">tutorial-parameters</code></dt><dd>A comma-delimited list of <code class="docutils literal notranslate">name=value</code> pairs. For the sake of simplicity, we’ll assume there will never be any commas in the values. </dd> </dl> If the username and password match what is stored in the file, we read the configuration information, store it in a <code class="docutils literal notranslate">GuacamoleConfiguration</code>, and return the configuration within a set, telling Guacamole that this user is authorized but only to access the configurations returned. Upstream, we always place the properties of authentication providers in their own class, and so we will also do that here in this tutorial, as it keeps things organized. <div class="highlight-java notranslate"><div class="highlight"><pre>package org.apache.guacamole.auth; import org.apache.guacamole.properties.StringGuacamoleProperty; /** * Utility class containing all properties used by the custom authentication * tutorial. The properties defined here must be specified within * guacamole.properties to configure the tutorial authentication provider. */ public class TutorialGuacamoleProperties { /** * This class should not be instantiated. */ private TutorialGuacamoleProperties() {} /** * The only user to allow. */ public static final StringGuacamoleProperty TUTORIAL_USER = new StringGuacamoleProperty() { @Override public String getName() { return "tutorial-user"; } }; /** * The password required for the specified user. */ public static final StringGuacamoleProperty TUTORIAL_PASSWORD = new StringGuacamoleProperty() { @Override public String getName() { return "tutorial-password"; } }; /** * The protocol to use when connecting. */ public static final StringGuacamoleProperty TUTORIAL_PROTOCOL = new StringGuacamoleProperty() { @Override public String getName() { return "tutorial-protocol"; } }; /** * All parameters associated with the connection, as a comma-delimited * list of name="value" */ public static final StringGuacamoleProperty TUTORIAL_PARAMETERS = new StringGuacamoleProperty() { @Override public String getName() { return "tutorial-parameters"; } }; } </pre></div> </div> Normally, we would define a new type of <code class="docutils literal notranslate">GuacamoleProperty</code> to handle the parsing of the parameters required by <code class="docutils literal notranslate">TUTORIAL_PARAMETERS</code>, but for the sake of simplicity, parsing of this parameter will be embedded in the authentication function later. You will need to modify your existing <code class="docutils literal notranslate">guacamole.properties</code> file, adding each of the above properties to describe one of your available connections. <div class="highlight-none notranslate"><div class="highlight"><pre># Username and password tutorial-user: tutorial tutorial-password: password # Connection information tutorial-protocol: vnc tutorial-parameters: hostname=localhost, port=5900 </pre></div> </div> Once these properties and their accessor class are in place, it’s simple enough to read the properties within <code class="docutils literal notranslate">getAuthorizedConfigurations()</code> and authenticate the user based on their username and password. <div class="highlight-java notranslate"><div class="highlight"><pre>@Override public Map<String, GuacamoleConfiguration> getAuthorizedConfigurations(Credentials credentials) throws GuacamoleException { // Get the Guacamole server environment Environment environment = LocalEnvironment.getInstance(); // Get username from guacamole.properties String username = environment.getRequiredProperty( TutorialGuacamoleProperties.TUTORIAL_USER ); // If wrong username, fail if (!username.equals(credentials.getUsername())) return null; // Get password from guacamole.properties String password = environment.getRequiredProperty( TutorialGuacamoleProperties.TUTORIAL_PASSWORD ); // If wrong password, fail if (!password.equals(credentials.getPassword())) return null; // Successful login. Return configurations (STUB) return new HashMap<String, GuacamoleConfiguration>(); } </pre></div> </div> As is, the authentication provider will work in its current state in that the correct username and password will authenticate the user, while an incorrect username or password will not, but we still aren’t returning an actual map of configurations. We need to construct the configuration based on the properties in the <code class="docutils literal notranslate">guacamole.properties</code> file after the user has been authenticated, and return that configuration to the web application. </section> <section id="parsing-the-configuration"> <h2>Parsing the configuration<a class="headerlink" href="#parsing-the-configuration" title="Link to this heading"></a></h2> The only remaining task before we have a fully-functioning authentication provider is to actually parse the configuration from the <code class="docutils literal notranslate">guacamole.properties</code> file. <div class="highlight-java notranslate"><div class="highlight"><pre>@Override public Map<String, GuacamoleConfiguration> getAuthorizedConfigurations(Credentials credentials) throws GuacamoleException { // Get the Guacamole server environment Environment environment = LocalEnvironment.getInstance(); // Get username from guacamole.properties String username = environment.getRequiredProperty( TutorialGuacamoleProperties.TUTORIAL_USER ); // If wrong username, fail if (!username.equals(credentials.getUsername())) return null; // Get password from guacamole.properties String password = environment.getRequiredProperty( TutorialGuacamoleProperties.TUTORIAL_PASSWORD ); // If wrong password, fail if (!password.equals(credentials.getPassword())) return null; // Successful login. Return configurations. Map<String, GuacamoleConfiguration> configs = new HashMap<String, GuacamoleConfiguration>(); // Create new configuration GuacamoleConfiguration config = new GuacamoleConfiguration(); // Set protocol specified in properties config.setProtocol(environment.getRequiredProperty( TutorialGuacamoleProperties.TUTORIAL_PROTOCOL )); // Set all parameters, splitting at commas for (String parameterValue : environment.getRequiredProperty( TutorialGuacamoleProperties.TUTORIAL_PARAMETERS ).split(",\\s*")) { // Find the equals sign int equals = parameterValue.indexOf('='); if (equals == -1) throw new GuacamoleServerException("Required equals sign missing"); // Get name and value from parameter string String name = parameterValue.substring(0, equals); String value = parameterValue.substring(equals+1); // Set parameter as specified config.setParameter(name, value); } configs.put("Tutorial Connection", config); return configs; } </pre></div> </div> The extension is now complete and can be built as described earlier in <a class="reference internal" href="#custom-auth-building">Building the extension</a>. </section> <section id="installing-the-extension"> <h2>Installing the extension<a class="headerlink" href="#installing-the-extension" title="Link to this heading"></a></h2> Guacamole extensions are self-contained <code class="docutils literal notranslate">.jar</code> files which are installed by being placed within <code class="docutils literal notranslate">GUACAMOLE_HOME/extensions</code>, and this extension is no different. As described in <a class="reference internal" href="configuring-guacamole.html">Configuring Guacamole</a>, <code class="docutils literal notranslate">GUACAMOLE_HOME</code> is a placeholder used to refer to the directory that Guacamole uses to locate its configuration files and extensions. Typically, this will be the <code class="docutils literal notranslate">.guacamole</code> directory within the home directory of the user running Tomcat. To install your extension, ensure that the required properties have been added to your <code class="docutils literal notranslate">guacamole.properties</code>, copy the <code class="docutils literal notranslate">target/guacamole-auth-tutorial-1.5.5.jar</code> file into <code class="docutils literal notranslate">GUACAMOLE_HOME/extensions</code> and restart Tomcat. Guacamole will automatically load your extension, logging an informative message that it has done so: <div class="highlight-none notranslate"><div class="highlight"><pre>Extension "Tutorial Authentication Extension" loaded. </pre></div> </div> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="custom-protocols.html" class="btn btn-neutral float-left" title="Adding new protocols" accesskey="p" rel="prev"> Previous</a> <a href="event-listeners.html" class="btn btn-neutral float-right" title="Event listeners" accesskey="n" rel="next">Next </a> </div> <hr/> <div role="contentinfo"> 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. </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/custom-auth.html (523 lines of code) (raw):