doc/gug/guacamole-ext.html

<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>guacamole-ext — Apache Guacamole Manual v1.5.3</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"></script> <script src="_static/_sphinx_javascript_frameworks_compat.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script src="_static/doctools.js"></script> <script src="_static/sphinx_highlight.js"></script> <script src="_static/tabs.js"></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="Adding new protocols" href="custom-protocols.html" /> <link rel="prev" title="guacamole-common-js" href="guacamole-common-js.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.3 </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 current"><a class="current reference internal" href="#">guacamole-ext</a><ul> <li class="toctree-l2"><a class="reference internal" href="#guacamole-extension-format">Guacamole extension format</a><ul> <li class="toctree-l3"><a class="reference internal" href="#extension-manifest">Extension manifest</a></li> <li class="toctree-l3"><a class="reference internal" href="#updating-existing-html">Updating existing HTML</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#accessing-the-server-configuration">Accessing the server configuration</a><ul> <li class="toctree-l3"><a class="reference internal" href="#custom-properties">Custom properties</a></li> <li class="toctree-l3"><a class="reference internal" href="#advanced-configuration">Advanced configuration</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#authentication-providers">Authentication providers</a><ul> <li class="toctree-l3"><a class="reference internal" href="#simpleauthenticationprovider"><code class="docutils literal notranslate">SimpleAuthenticationProvider</code></a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#the-usercontext">The <code class="docutils literal notranslate">UserContext</code></a></li> <li class="toctree-l2"><a class="reference internal" href="#directory-classes"><code class="docutils literal notranslate">Directory</code> classes</a></li> <li class="toctree-l2"><a class="reference internal" href="#rest-resources">REST resources</a></li> <li class="toctree-l2"><a class="reference internal" href="#permissions">Permissions</a><ul> <li class="toctree-l3"><a class="reference internal" href="#system-permissions">System permissions</a></li> <li class="toctree-l3"><a class="reference internal" href="#object-permissions">Object permissions</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#connections">Connections</a></li> <li class="toctree-l2"><a class="reference internal" href="#managing-sharing-active-connections">Managing/sharing active connections</a></li> </ul> </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> 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">guacamole-ext</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/guacamole-ext.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="guacamole-ext"> <h1>guacamole-ext<a class="headerlink" href="#guacamole-ext" title="Permalink to this heading"></a></h1> While not strictly part of the Java API provided by the Guacamole project, guacamole-ext is an API exposed by the Guacamole web application within a separate project such that extensions, specifically authentication providers, can be written to tweak Guacamole to fit well in existing deployments. Extensions to Guacamole can: <ol class="arabic simple"> <li>Provide alternative authentication methods and sources of connection/user data.</li> <li>Provide event listeners that will be notified as Guacamole performs tasks such as authentication and tunnel connection.</li> <li>Theme or brand Guacamole through additional CSS files and static resources.</li> <li>Extend Guacamole’s JavaScript code by providing JavaScript that will be loaded automatically.</li> <li>Add additional display languages, or alter the translation strings of existing languages.</li> </ol> <section id="guacamole-extension-format"> <h2>Guacamole extension format<a class="headerlink" href="#guacamole-extension-format" title="Permalink to this heading"></a></h2> Guacamole extensions are standard Java <code class="docutils literal notranslate">.jar</code> files which contain all classes, library <code class="docutils literal notranslate">.jar</code> files, and resources required by the extension, as well as the Guacamole extension manifest. There is no set structure to an extension except that: <ol class="arabic simple"> <li>The <code class="docutils literal notranslate">guac-manifest.json</code> manifest must be in the root of the archive.</li> <li>Any required library <code class="docutils literal notranslate">.jar</code> files that will not be placed within <a class="reference internal" href="configuring-guacamole.html#guacamole-home"><code class="docutils literal notranslate">GUACAMOLE_HOME/lib/</code></a> must be in the root of the archive.</li> <li>Java classes and packages for the extension itself (or for unpacked dependencies of the extension) will be read relative to the archive root, as well.</li> </ol> Beyond this, the semantics and locations associated with all other resources within the extension are determined by the extension manifest alone. <section id="extension-manifest"> <h3>Extension manifest<a class="headerlink" href="#extension-manifest" title="Permalink to this heading"></a></h3> The Guacamole extension manifest is a single JSON file, <code class="docutils literal notranslate">guac-manifest.json</code>, which describes the location of each resource, the type of each resource, and the version of Guacamole that the extension was built for. The manifest can contain the following properties: <dl class="simple myst"> <dt><code class="docutils literal notranslate">guacamoleVersion</code></dt><dd>The version string of the Guacamole release that this extension is written for. This property is required for all extensions. The special version string <code class="docutils literal notranslate">"*"</code> can be used if the extension does not depend on a particular version of Guacamole, but be careful - this will bypass version compatibility checks, and should never be used if the extension does more than basic theming or branding. </dd> <dt><code class="docutils literal notranslate">name</code></dt><dd>A human-readable name for the extension. This property is required for all extensions. When your extension is successfully loaded, a message acknowledging the successful loading of your extension by name will be logged. </dd> <dt><code class="docutils literal notranslate">namespace</code></dt><dd>A unique string which identifies your extension. This property is required for all extensions. This string should be unique enough that it is unlikely to collide with the namespace of any other extension. If your extension contains static resources, those resources will be served at a path derived from the namespace provided here. </dd> <dt><code class="docutils literal notranslate">authProviders</code></dt><dd>An array of the classnames of all <code class="docutils literal notranslate">AuthenticationProvider</code> subclasses provided by this extension. </dd> <dt><code class="docutils literal notranslate">listeners</code></dt><dd>An array of the classnames of all <code class="docutils literal notranslate">Listener</code> subclasses provided by this extension. </dd> <dt><code class="docutils literal notranslate">js</code></dt><dd>An array of all JavaScript files within the extension. All paths within this array must be relative paths, and will be interpreted relative to the root of the archive. JavaScript files declared here will be automatically loaded when the web application loads within the user’s browser. </dd> <dt><code class="docutils literal notranslate">css</code></dt><dd>An array of all CSS files within the extension. All paths within this array must be relative paths, and will be interpreted relative to the root of the archive. CSS files declared here will be automatically applied when the web application loads within the user’s browser. </dd> <dt><code class="docutils literal notranslate">html</code></dt><dd>An array of all HTML files within the extension that should be used to update or replace existing HTML within the Guacamole interface. All paths within this array must be relative paths, and will be interpreted relative to the root of the archive. HTML files declared here will be automatically applied to other HTML within the Guacamole interface when the web application loads within the user’s browser. The manner in which the files are applied is dictated by <code class="docutils literal notranslate"><meta ...></code> tags within those same files. </dd> <dt><code class="docutils literal notranslate">translations</code></dt><dd>An array of all translation files within the extension. All paths within this array must be relative paths, and will be interpreted relative to the root of the archive. Translation files declared here will be automatically added to the available languages. If a translation file provides a language that already exists within Guacamole, its strings will override the strings of the existing translation. </dd> <dt><code class="docutils literal notranslate">resources</code></dt><dd>An object where each property name is the name of a web resource file, and each value is the mimetype for that resource. All paths within this object must be relative paths, and will be interpreted relative to the root of the archive. Web resources declared here will be made available to the application at <code class="samp docutils literal notranslate">app/ext/NAMESPACE/PATH</code>, where <code class="docutils literal notranslate">NAMESPACE</code> is the value of the namespace property, and <code class="docutils literal notranslate">PATH</code> is the declared web resource filename. </dd> </dl> The only absolutely required properties are <code class="docutils literal notranslate">guacamoleVersion</code>, <code class="docutils literal notranslate">name</code>, and <code class="docutils literal notranslate">namespace</code>, as they are used to identify the extension and for compatibility checks. The most minimal <code class="docutils literal notranslate">guac-manifest.json</code> will look something like this: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "guacamoleVersion" : "1.5.3", "name" : "My Extension", "namespace" : "my-extension" } </pre></div> </div> This will allow the extension to load, but does absolutely nothing otherwise. Lacking the semantic information provided by the other properties, no other files within the extension will be used. A typical <code class="docutils literal notranslate">guac-manifest.json</code> for an extension providing theming or branding would be more involved: <div class="highlight-json notranslate"><div class="highlight"><pre>{ "guacamoleVersion" : "1.5.3", "name" : "My Extension", "namespace" : "my-extension", "css" : [ "theme.css" ], "html" : [ "loginDisclaimer.html" ], "resources" : { "images/logo.png" : "image/png", "images/cancel.png" : "image/png", "images/delete.png" : "image/png" } } </pre></div> </div> </section> <section id="updating-existing-html"> <h3>Updating existing HTML<a class="headerlink" href="#updating-existing-html" title="Permalink to this heading"></a></h3> The existing HTML structure of Guacamole’s interface can be modified by extensions through special “patch” HTML files declared by the html property in <code class="docutils literal notranslate">guac-manifest.json</code>. These files are HTML fragments and are identical to any other HTML file except that they contain Guacamole-specific meta tags that instruct Guacamole to modify its own HTML in a particular way. Each meta tag takes the following form: <div class="highlight-html notranslate"><div class="highlight"><pre><meta name="NAME" content="SELECTOR"> </pre></div> </div> where <code class="docutils literal notranslate">SELECTOR</code> is a CSS selector that matches the elements within the Guacamole interface that serve as a basis for the modification, and <code class="docutils literal notranslate">NAME</code> is any one of the following defined modifications: <dl class="simple myst"> <dt><code class="docutils literal notranslate">before</code></dt><dd>Inserts the specified HTML immediately before any element matching the CSS selector. </dd> <dt><code class="docutils literal notranslate">after</code></dt><dd>Inserts the specified HTML immediately after any element matching the CSS selector. </dd> <dt><code class="docutils literal notranslate">replace</code></dt><dd>Replaces any element matching the CSS selector with the specified HTML. </dd> <dt><code class="docutils literal notranslate">before-children</code></dt><dd>Inserts the specified HTML immediately before the first child (if any) of any element matching the CSS selector. If a matching element has no children, the HTML simply becomes the entire contents of the matching element. </dd> <dt><code class="docutils literal notranslate">after-children</code></dt><dd>Inserts the specified HTML immediately after the last child (if any) of any element matching the CSS selector. If a matching element has no children, the HTML simply becomes the entire contents of the matching element. </dd> <dt><code class="docutils literal notranslate">replace-children</code></dt><dd>Replaces the entire contents of any element matching the CSS selector with the specified HTML. </dd> </dl> For example, to add a welcome message and link to some corporate privacy policy (a fairly common need), you would add an HTML file like the following: <div class="highlight-html notranslate"><div class="highlight"><pre><meta name="after" content=".login-ui .login-dialog"> <div class="welcome"> <h2>Welcome to our Guacamole server!</h2> <p> Please be sure to read our <a href="/path/to/some/privacy.html">privacy policy</a> before continuing. </p> </div> </pre></div> </div> After the extension is installed and Guacamole is restarted, the “welcome” div and its contents will automatically be inserted directly below the login dialog (the only element that would match <code class="docutils literal notranslate">.login-ui .login-dialog</code>) as if they were part of Guacamole’s HTML in the first place. An example of an extension that modifies style and HTML components for the purpose of providing custom “branding” of the Guacamole interface can be found in the <code class="docutils literal notranslate">doc/guacamole-branding-example</code> directory of the guacamole-client source code, which can be found here: <a class="reference external" href="https://github.com/apache/guacamole-client/tree/master/doc/guacamole-branding-example">https://github.com/apache/guacamole-client/tree/master/doc/guacamole-branding-example</a> </section> </section> <section id="accessing-the-server-configuration"> <h2>Accessing the server configuration<a class="headerlink" href="#accessing-the-server-configuration" title="Permalink to this heading"></a></h2> The configuration of the Guacamole server is exposed through the <code class="docutils literal notranslate">Environment</code> interface, specifically the <code class="docutils literal notranslate">LocalEnvironment</code> implementation of this interface. Through <code class="docutils literal notranslate">Environment</code>, you can access all properties declared within <code class="docutils literal notranslate">guacamole.properties</code>, determine the proper hostname/port of guacd, and access the contents of <code class="docutils literal notranslate">GUACAMOLE_HOME</code>. <section id="custom-properties"> <h3>Custom properties<a class="headerlink" href="#custom-properties" title="Permalink to this heading"></a></h3> If your extension requires generic, unstructured configuration parameters, <code class="docutils literal notranslate">guacamole.properties</code> is a reasonable and simple location for them. The <code class="docutils literal notranslate">Environment</code> interface provides direct access to <code class="docutils literal notranslate">guacamole.properties</code> and simple mechanisms for reading and parsing the properties therein. The value of a property can be retrieved by calling <code class="docutils literal notranslate">getProperty()</code>, which will return <code class="docutils literal notranslate">null</code> or a default value for undefined properties, or <code class="docutils literal notranslate">getRequiredProperty()</code>, which will throw an exception for undefined properties. For convenience, guacamole-ext contains several pre-defined property base classes for common types: <dl class="simple myst"> <dt><code class="docutils literal notranslate">BooleanGuacamoleProperty</code></dt><dd>The values “true” and “false” are parsed as their corresponding <code class="docutils literal notranslate">Boolean</code> values. Any other value results in a parse error. </dd> <dt><code class="docutils literal notranslate">IntegerGuacamoleProperty</code></dt><dd>Numeric strings are parsed as <code class="docutils literal notranslate">Integer</code> values. Non-numeric strings will result in a parse error. </dd> <dt><code class="docutils literal notranslate">LongGuacamoleProperty</code></dt><dd>Numeric strings are parsed as <code class="docutils literal notranslate">Long</code> values. Non-numeric strings will result in a parse error. </dd> <dt><code class="docutils literal notranslate">StringGuacamoleProperty</code></dt><dd>The property value is returned as an untouched <code class="docutils literal notranslate">String</code>. No parsing is performed, and parse errors cannot occur. </dd> <dt><code class="docutils literal notranslate">FileGuacamoleProperty</code></dt><dd>The property is interpreted as a filename, and a new <code class="docutils literal notranslate">File</code> pointing to that filename is returned. If the filename is invalid, a parse error will be thrown. Note that the file need not exist or be accessible for the filename to be valid. </dd> </dl> To use these types, you must extend the base class, implementing the <code class="docutils literal notranslate">getName()</code> function to identify your property. Typically, you would declare these properties as static members of some class containing all properties relevant to your extension: <div class="highlight-java notranslate"><div class="highlight"><pre>public class MyProperties { public static MY_PROPERTY = new IntegerGuacamoleProperty() { @Override public String getName() { return "my-property"; } }; } </pre></div> </div> Your property can then be retrieved with <code class="docutils literal notranslate">getProperty()</code> or <code class="docutils literal notranslate">getRequiredProperty()</code>: <div class="highlight-java notranslate"><div class="highlight"><pre>Integer value = environment.getProperty(MyProperties.MY_PROPERTY); </pre></div> </div> If you need more sophisticated parsing, you can also implement your own property types by implementing the <code class="docutils literal notranslate">GuacamoleProperty</code> interface. The only functions to implement are <code class="docutils literal notranslate">getName()</code>, which returns the name of the property, and <code class="docutils literal notranslate">parseValue()</code>, which parses a given string and returns its value. </section> <section id="advanced-configuration"> <h3>Advanced configuration<a class="headerlink" href="#advanced-configuration" title="Permalink to this heading"></a></h3> If you need more structured data than provided by simple properties, you can place completely arbitrary files in a hierarchy of your choosing anywhere within <code class="docutils literal notranslate">GUACAMOLE_HOME</code> as long as you avoid placing your files in directories reserved for other purposes as described above. The <code class="docutils literal notranslate">Environment</code> interface exposes the location of <code class="docutils literal notranslate">GUACAMOLE_HOME</code> through the <code class="docutils literal notranslate">getGuacamoleHome()</code> function. This function returns a standard Java <code class="docutils literal notranslate">File</code> which can then be used to locate other files or directories within <code class="docutils literal notranslate">GUACAMOLE_HOME</code>: <div class="highlight-java notranslate"><div class="highlight"><pre>File myConfigFile = new File(environment.getGuacamoleHome(), "my-config.xml"); </pre></div> </div> There is no guarantee that <code class="docutils literal notranslate">GUACAMOLE_HOME</code> or your file will exist, and you should verify this before proceeding further in your extension’s configuration process, but once this is done you can simply parse your file as you see fit. </section> </section> <section id="authentication-providers"> <h2>Authentication providers<a class="headerlink" href="#authentication-providers" title="Permalink to this heading"></a></h2> Guacamole’s authentication system is driven by authentication providers, which are classes which implement the <code class="docutils literal notranslate">AuthenticationProvider</code> interface defined by guacamole-ext. When any page within Guacamole is visited, the following process occurs: <ol class="arabic"> <li>All currently installed extensions are polled, in lexicographic order of their filenames, by invoking the <code class="docutils literal notranslate">getAuthenticatedUser()</code> function with a <code class="docutils literal notranslate">Credentials</code> object constructed with the contents of the HTTP request. The credentials given are abstract. While the <code class="docutils literal notranslate">Credentials</code> object provides convenience access to a traditional username and password, implementations are not required to use usernames and passwords. The entire contents of the HTTP request is at your disposal, including parameters, cookies, and SSL information. </li> <li>If an authentication attempt fails, the extension throws either a <code class="docutils literal notranslate">GuacamoleInsufficientCredentialsException</code> (if more credentials are needed before validity can be determined) or <code class="docutils literal notranslate">GuacamoleInvalidCredentialsException</code> (if the credentials are technically sufficient, but are invalid as provided). If all extensions fail to authenticate the user, the contents of the exception thrown by the first extension to fail are used to produce the user login prompt. Note that this means there is no “login screen” in Guacamole per se; the prompt for credentials for unauthenticated users is determined purely based on the needs of the extension as declared within the authentication failure itself. If an authentication attempt succeeds, the extension returns an instance of <code class="docutils literal notranslate">AuthenticatedUser</code> describing the identity of the user that just authenticated, and no further extensions are polled. </li> <li>If authentication has succeeded, and thus an <code class="docutils literal notranslate">AuthenticatedUser</code> is available, that <code class="docutils literal notranslate">AuthenticatedUser</code> is passed to the <code class="docutils literal notranslate">getUserContext()</code> function of all extensions’ authentication providers. Each extension now has the opportunity to provide access to data for a user, even if that extension did not originally authenticate the user. If no <code class="docutils literal notranslate">UserContext</code> is returned for the given <code class="docutils literal notranslate">AuthenticatedUser</code>, then that extension has simply refused to provide data for that user. The Guacamole interface will transparently unify the data from each extension, providing the user with a view of all available connections. If the user has permission to modify or administer any objects associated with an extension, access to the administrative interface will be exposed as well, again with a unified view of all applicable objects. </li> </ol> <div class="admonition important"> Important Because authentication is decoupled from data storage/access, you do not need to implement full-blown data storage if you only wish to provide an additional authentication mechanism. You can instead implement only the authentication portion of an <code class="docutils literal notranslate">AuthenticationProvider</code>, and otherwise rely on the storage and features provided by other extensions, such as the <a class="reference internal" href="jdbc-auth.html">database authentication extension</a>. </div> The Guacamole web application includes a basic authentication provider implementation which parses an XML file to determine which users exist, their corresponding passwords, and what configurations those users have access to. This is the part of Guacamole that reads the <code class="docutils literal notranslate">user-mapping.xml</code> file. If you use a custom authentication provider for your authentication, this file will probably not be required. The community has implemented authentication providers which access databases, use LDAP, or even perform no authentication at all, redirecting all users to a single configuration specified in <code class="docutils literal notranslate">guacamole.properties</code>. A minimal authentication provider is implemented in the tutorials later, and the upstream authentication provider implemented within Guacamole, as well as the authentication providers implemented by the community, are good examples for how authentication can be extended without having to implement a whole new web application. <section id="simpleauthenticationprovider"> <h3><code class="docutils literal notranslate">SimpleAuthenticationProvider</code><a class="headerlink" href="#simpleauthenticationprovider" title="Permalink to this heading"></a></h3> The <code class="docutils literal notranslate">SimpleAuthenticationProvider</code> class provides a much simpler means of implementing authentication when you do not require the ability to add and remove users and connections. It is an abstract class and requires only one function implementation: <code class="docutils literal notranslate">getAuthorizedConfigurations()</code>. This function is required to return a <code class="docutils literal notranslate">Map</code> of unique IDs to configurations, where these configurations are all configurations accessible with the provided credentials. As before, the credentials given are abstract. You are not required to use usernames and passwords. The configurations referred to by the function name are instances of <code class="docutils literal notranslate">GuacamoleConfiguration</code> (part of guacamole-common), which is just a wrapper around a protocol name and set of parameter name/value pairs. The name of the protocol to use and a set of parameters is the minimum information required for other parts of the Guacamole API to complete the handshake required by the Guacamole protocol. When a class that extends <code class="docutils literal notranslate">SimpleAuthenticationProvider</code> is asked for more advanced operations by the web application, <code class="docutils literal notranslate">SimpleAuthenticationProvider</code> simply returns that there is no permission to do so. This effectively disables all administrative functionality within the web interface. If you choose to go the simple route, most of the rest of this chapter is irrelevant. Permissions, security model, and various classes will be discussed that are all handled for you automatically by <code class="docutils literal notranslate">SimpleAuthenticationProvider</code>. </section> </section> <section id="the-usercontext"> <h2>The <code class="docutils literal notranslate">UserContext</code><a class="headerlink" href="#the-usercontext" title="Permalink to this heading"></a></h2> The <code class="docutils literal notranslate">UserContext</code> is the root of all data-related operations. It is used to list, create, modify, or delete users and connections, as well as to query available permissions. If an extension is going to provide access to data of any sort, it must do so through the <code class="docutils literal notranslate">UserContext</code>. The Guacamole web application uses permissions queries against the <code class="docutils literal notranslate">UserContext</code> to determine what operations to present, but beware that it is up to the <code class="docutils literal notranslate">UserContext</code> to actually enforce these restrictions. The Guacamole web application will not enforce restrictions on behalf of the <code class="docutils literal notranslate">UserContext</code>. The <code class="docutils literal notranslate">UserContext</code> is the sole means of entry and the sole means of modification available to a logged-in user. If the <code class="docutils literal notranslate">UserContext</code> refuses to perform an operation (by throwing an exception), the user cannot perform the operation at all. </section> <section id="directory-classes"> <h2><code class="docutils literal notranslate">Directory</code> classes<a class="headerlink" href="#directory-classes" title="Permalink to this heading"></a></h2> Access to objects beneath the <code class="docutils literal notranslate">UserContext</code> is given through <code class="docutils literal notranslate">Directory</code> classes. These <code class="docutils literal notranslate">Directory</code> classes are similar to Java collections, but they also embody update and batching semantics. Objects can be retrieved from a <code class="docutils literal notranslate">Directory</code> using its <code class="docutils literal notranslate">get()</code> function and added or removed with <code class="docutils literal notranslate">add()</code> and <code class="docutils literal notranslate">remove()</code> respectively, but objects already in the set can also be updated by passing an updated object to its <code class="docutils literal notranslate">update()</code> function. An implementation of a <code class="docutils literal notranslate">Directory</code> can rely on these functions to define the semantics surrounding all operations. The <code class="docutils literal notranslate">add()</code> function is called only when creating new objects, the <code class="docutils literal notranslate">update()</code> function is called only when updating an object previously retrieved with <code class="docutils literal notranslate">get()</code>, and <code class="docutils literal notranslate">remove()</code> is called only when removing an existing object by its identifier. When implementing an <code class="docutils literal notranslate">AuthenticationProvider</code>, you must ensure that the <code class="docutils literal notranslate">UserContext</code> will only return <code class="docutils literal notranslate">Directory</code> classes that automatically enforce the permissions associated with all objects and the associated user. </section> <section id="rest-resources"> <h2>REST resources<a class="headerlink" href="#rest-resources" title="Permalink to this heading"></a></h2> Arbitrary REST resources may be exposed by extensions at the <code class="docutils literal notranslate">AuthenticationProvider</code> level, if the resource does not require an associated authenticated user, or at the <code class="docutils literal notranslate">UserContext</code> level, if the resource should be available to authenticated users only. In both cases, the REST resource is provided through implementing the <code class="docutils literal notranslate">getResource()</code> function, returning an object which is annotated with JAX-RS annotations (JSR 311). The resource returned by <code class="docutils literal notranslate">getResource()</code> functions as the root resource, providing access to other resources beneath itself. The root resource for the <code class="docutils literal notranslate">AuthenticationProvider</code> is exposed at <code class="samp docutils literal notranslate">PATH/api/ext/IDENTIFIER</code>, and the root resource for the <code class="docutils literal notranslate">UserContext</code> is exposed at <code class="samp docutils literal notranslate">PATH/api/session/ext/IDENTIFIER</code>, where <code class="docutils literal notranslate">PATH</code> is the path to which Guacamole has been deployed (typically <code class="docutils literal notranslate">/guacamole/</code>) and <code class="docutils literal notranslate">IDENTIFIER</code> is the unique identifier for the <code class="docutils literal notranslate">AuthenticationProvider</code>, as returned by <code class="docutils literal notranslate">getIdentifier()</code>. The behavior of extension REST resources is generally left entirely to the implementation, with the exception that the “token” request parameter is reserved for use by Guacamole. This parameter contains the user’s authentication token when the user is logged in, and must be present on all requests which require authentication. Though not relevant to REST resources exposed at the <code class="docutils literal notranslate">AuthenticationProvider</code> level, resources exposed at the <code class="docutils literal notranslate">UserContext</code> level inherently require the “token” parameter to be present, as it is the sole means of locating the user’s session. </section> <section id="permissions"> <h2>Permissions<a class="headerlink" href="#permissions" title="Permalink to this heading"></a></h2> The permissions system within guacamole-ext is an advisory system. It is the means by which an authentication module describes to the web application what a user is allowed to do. The body of permissions granted to a user describes which objects that user can see and what they can do to those objects, and thus suggests how the Guacamole interface should appear to that user. Permissions are not the means by which access is restricted; they are purely a means of describing access level. An implementation may internally use the permission objects to define restrictions, but this is not required. It is up to the implementation to enforce its own restrictions by throwing exceptions when an operation is not allowed, and to correctly communicate the abilities of individual users through these permissions. The permissions available to a user are exposed through the <code class="docutils literal notranslate">SystemPermissionSet</code> and <code class="docutils literal notranslate">ObjectPermissionSet</code> classes which are accessible through the <code class="docutils literal notranslate">UserContext</code>. These classes also serve as the means for manipulating the permissions granted to a user. <section id="system-permissions"> <h3>System permissions<a class="headerlink" href="#system-permissions" title="Permalink to this heading"></a></h3> System permissions describe access to operations that manipulate the system as a whole, rather than specific objects. This includes the creation of new objects, as object creation directly affects the system, and per-object controls cannot exist before the object is actually created. <dl class="simple myst"> <dt><code class="docutils literal notranslate">ADMINISTER</code></dt><dd>The user is a super-user - the Guacamole equivalent of root. They are allowed to manipulate of system-level permissions and all other objects. This permission implies all others. </dd> <dt><code class="docutils literal notranslate">CREATE_CONNECTION</code></dt><dd>The user is allowed to create new connections. If a user has this permission, the management interface will display components related to connection creation. </dd> <dt><code class="docutils literal notranslate">CREATE_CONNECTION_GROUP</code></dt><dd>The user is allowed to create new connection groups. If a user has this permission, the management interface will display components related to connection group creation. </dd> <dt><code class="docutils literal notranslate">CREATE_SHARING_PROFILE</code></dt><dd>The user is allowed to create new sharing profiles. If a user has this permission, the management interface will display components related to sharing profile creation. </dd> <dt><code class="docutils literal notranslate">CREATE_USER</code></dt><dd>The user is allowed to create other users. If a user has this permission, the management interface will display components related to user creation. </dd> </dl> </section> <section id="object-permissions"> <h3>Object permissions<a class="headerlink" href="#object-permissions" title="Permalink to this heading"></a></h3> Object permissions describe access to operations that affect a particular object. Guacamole currently defines four types of objects which can be associated with permissions: users, connections, connection groups, and sharing profiles. Each object permission associates a single user with an action that may be performed on a single object. <dl class="simple myst"> <dt><code class="docutils literal notranslate">ADMINISTER</code></dt><dd>The user may grant or revoke permissions involving this object. “Involving”, in this case, refers to either side of the permission association, and includes both the user to whom the permission is granted and the object the permission affects. </dd> <dt><code class="docutils literal notranslate">DELETE</code></dt><dd>The user may delete this object. This is distinct from the <code class="docutils literal notranslate">ADMINISTER</code> permission which deals only with permissions. A user with this permission will see the “Delete” button when applicable. </dd> <dt><code class="docutils literal notranslate">READ</code></dt><dd>The user may see that this object exists and read the properties of that object. Note that the implementation is not required to divulge the true underlying properties of any object. The parameters of a connection or sharing profile, the type or contents of a connection group, the password of a user, etc. all need not be exposed. This is particularly important from the perspective of security when it comes to connections, as the parameters of a connection are only truly needed when a connection is being modified, and likely should not be exposed otherwise. The actual connection operation is always performed internally by the authentication provider, and thus does not require client-side knowledge of anything beyond the connection’s existence. </dd> <dt><code class="docutils literal notranslate">UPDATE</code></dt><dd>The user may change the properties of this object. In the case of users, this means the user’s password can be altered. Permissions are not considered properties of a user, nor objects in their own right, but rather associations between a user and an action which may involve another object. The properties of a connection include its name, protocol, parent connection group, and parameters. The properties of a connection group include its name, type, parent connection group, and children. The properties of a sharing profile include its name, primary connection, and parameters. </dd> </dl> </section> </section> <section id="connections"> <h2>Connections<a class="headerlink" href="#connections" title="Permalink to this heading"></a></h2> Guacamole connections are organized in a hierarchy made up of connection groups, which each act as folders organizing the connections themselves. The hierarchy is accessed through the root-level connection group, exposed by <code class="docutils literal notranslate">getRootConnectionGroup()</code> by the <code class="docutils literal notranslate">UserContext</code>. The connections and connection groups exposed beneath the root connection group must also be accessible directly through the connection and connection group directories exposed by <code class="docutils literal notranslate">getConnectionDirectory()</code> and <code class="docutils literal notranslate">getConnectionGroupDirectory()</code> of the <code class="docutils literal notranslate">UserContext</code>. When a user attempts to use a connection the <code class="docutils literal notranslate">connect()</code> of the associated <code class="docutils literal notranslate">Connection</code> object will be invoked. It is then up to the implementation of this function to establish the TCP connection to guacd, perform the connection handshake (most likely via an <code class="docutils literal notranslate">InetGuacamoleSocket</code> wrapped within a <code class="docutils literal notranslate">ConfiguredGuacamoleSocket</code>), and then return a <code class="docutils literal notranslate">GuacamoleTunnel</code> which controls access to the established socket. Extensions may maintain historical record of connection use via <code class="docutils literal notranslate">ConnectionRecord</code> objects, which are exposed both at the <code class="docutils literal notranslate">Connection</code> level and across all connections via the <code class="docutils literal notranslate">UserContext</code>. Such record maintenance is optional, and it is expected that most implementations will simply return empty lists. <div class="admonition important"> Important If connection state will not be tracked by the extension, and the parameters associated with the connection will be known at the time the connection object is created, the <code class="docutils literal notranslate">SimpleConnection</code> implementation of <code class="docutils literal notranslate">Connection</code> can be used to make life easier. </div> </section> <section id="managing-sharing-active-connections"> <h2>Managing/sharing active connections<a class="headerlink" href="#managing-sharing-active-connections" title="Permalink to this heading"></a></h2> After a connection has been established, its underlying <code class="docutils literal notranslate">GuacamoleTunnel</code> can be exposed by a <code class="docutils literal notranslate">UserContext</code> through the <code class="docutils literal notranslate">Directory</code> returned by getActiveConnectionDirectory(). The <code class="docutils literal notranslate">ActiveConnection</code> objects accessible through this <code class="docutils literal notranslate">Directory</code> are the means by which an administrator may monitor or forcibly terminate another user’s connection, ultimately resulting in Guacamole invoking the <code class="docutils literal notranslate">close()</code> function of the underlying <code class="docutils literal notranslate">GuacamoleTunnel</code>, and also serve as the basis for screen sharing. Screen sharing is implemented through the use of <code class="docutils literal notranslate">SharingProfile</code> objects, exposed through yet another <code class="docutils literal notranslate">Directory</code> beneath the <code class="docutils literal notranslate">UserContext</code>. Each sharing profile is associated with a single connection that it can be used to share, referred to as the “primary connection”. If a user has read access to a sharing profile associated with their current connection, that sharing profile will be displayed as an option within <a class="reference internal" href="using-guacamole.html#client-share-menu">the share menu of the Guacamole menu</a>. The overall sharing process is as follows: <ol class="arabic simple"> <li>A user, having access to a sharing profile associated with their current active connection, clicks its option within the <a class="reference internal" href="using-guacamole.html#client-share-menu">share menu</a>.</li> <li>Guacamole locates the <code class="docutils literal notranslate">ActiveConnection</code> and invokes its <code class="docutils literal notranslate">getSharingCredentials()</code> function with the identifier of the sharing profile. The contents of the returned <code class="docutils literal notranslate">UserCredentials</code> object is used by Guacamole to generate a sharing link which can be given to other users.</li> <li>When another user visits the sharing link, the credentials embedded in the link are passed to the authentication providers associated with each installed extension. It is up to the extension that originally provided those credentials to authenticate the user and provide them with access to the shared connection.</li> <li>When the user attempts to connect to the shared connection, the extension establishes the connection using the ID of the connection being joined. This is not the connection identifier as dictated by guacamole-ext, but rather <a class="reference internal" href="guacamole-protocol.html#guacamole-protocol-joining">the unique ID assigned by guacd as required by the Guacamole protocol</a>. This ID can be retrieved from a <code class="docutils literal notranslate">ConfiguredGuacamoleSocket</code> via <code class="docutils literal notranslate">getConnectionID()</code>, and can be passed through a <code class="docutils literal notranslate">GuacamoleConfiguration</code> through <code class="docutils literal notranslate">setConnectionID()</code> (instead of specifying a protocol, as would be done for a brand new connection).</li> </ol> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="guacamole-common-js.html" class="btn btn-neutral float-left" title="guacamole-common-js" accesskey="p" rel="prev"> Previous</a> <a href="custom-protocols.html" class="btn btn-neutral float-right" title="Adding new protocols" accesskey="n" rel="next">Next </a> </div> <hr/> <div role="contentinfo"> Copyright © 2023 <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>  <script type="text/javascript"> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-75289145-1', 'auto'); ga('send', 'pageview'); </script> </body> </html>

doc/gug/guacamole-ext.html (742 lines of code) (raw):