doc/gug/event-listeners.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>Event listeners — 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="Writing your own Guacamole application" href="writing-you-own-guacamole-app.html" /> <link rel="prev" title="Custom authentication" href="custom-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.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"><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 current"><a class="current reference internal" href="#">Event listeners</a><ul> <li class="toctree-l2"><a class="reference internal" href="#a-guacamole-listener-extension-skeleton">A Guacamole listener 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="#handling-events">Handling events</a></li> <li class="toctree-l2"><a class="reference internal" href="#influencing-guacamole-by-event-veto">Influencing Guacamole by event veto</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="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">Event listeners</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/event-listeners.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="event-listeners"> <h1>Event listeners<a class="headerlink" href="#event-listeners" title="Permalink to this heading"></a></h1> Guacamole supports the delivery of event notifications to custom extensions. Developers can use listener extensions to integrate custom handling of events such as successful and failed authentications, and requests to connect and disconnect tunnels to desktop environments. A listener extension could be used, for example, to record authentication attempts in an external database for security auditing or alerting. By listening to tunnel lifecycle events, a listener extension could be used to help coordinate startup and shutdown of machine resources; particularly useful in cloud environments where minimizing running-but-idle resources is an important cost savings measure. For certain vetoable events, an event listener can even influence Guacamole’s behavior. For example, a listener can veto a successful authentication, effectively causing the authentication to be considered failed. Similarly, a listener can veto a tunnel connection, effectively preventing the tunnel from being connected to a virtual desktop resource. Custom event listeners are packaged using the same extension mechanism used for custom authentication providers. A single listener extension can include any number of classes that implement the listener interface. A single extension module can also include any combination of authentication providers and listeners, so developers can easily combine authentication providers with listeners designed to support them. To demonstrate the principles involved in receiving Guacamole event notifications, we will implement a simple listener extension that logs authentication events. While our approach simply writes event details to the same log used by the Guacamole web application, a listener could process these events in arbitrary ways, limited only by the imagination and ingenuity of the developer. <section id="a-guacamole-listener-extension-skeleton"> <h2>A Guacamole listener extension skeleton<a class="headerlink" href="#a-guacamole-listener-extension-skeleton" title="Permalink 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 listener extension is a <code class="docutils literal notranslate">pom.xml</code> file listing guacamole-ext as a dependency, a single <code class="docutils literal notranslate">.java</code> file implementing our stub of a listener, and a <code class="docutils literal notranslate">guac-manifest.json</code> file describing the extension and pointing to our listener class. <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-listener-tutorial</artifactId> <packaging>jar</packaging> <version>1.5.3</version> <name>guacamole-listener-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.3</version> <scope>provided</scope> </dependency>   <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <version>1.7.7</version> <scope>provided</scope> </dependency> </dependencies> </project> </pre></div> </div> Naturally, we need the actual listener 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.event.TutorialListener</code>. For now, we won’t actually do anything other than log the fact that an event notification was received. At this point, we’re just creating the skeleton for our listener extension. <div class="highlight-java notranslate"><div class="highlight"><pre>package org.apache.guacamole.event; import org.apache.guacamole.GuacamoleException; import org.apache.guacamole.net.event.listener.Listener; import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** * A Listener implementation intended to demonstrate basic use * of Guacamole's listener extension API. */ public class TutorialListener implements Listener { private static final Logger logger = LoggerFactory.getLogger(TutorialListener.class); @Override public void handleEvent(Object event) throws GuacamoleException { logger.info("received Guacamole event notification"); } } </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/event</code> as <code class="docutils literal notranslate">TutorialListener.java</code>. As you can see, implementing a listener is quite simple. There is a single <code class="docutils literal notranslate">Listener</code> interface to implement. All Guacamole event notifications will be delivered to your code by invoking the handleEvent method. We will see shortly how to use the passed event object to get the details of the event itself. 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 listener 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 listener 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.3", "name" : "Tutorial Listener Extension", "namespace" : "guac-listener-tutorial", "listeners" : [ "org.apache.guacamole.event.TutorialListener" ] } </pre></div> </div> </section> <section id="building-the-extension"> <h2>Building the extension<a class="headerlink" href="#building-the-extension" title="Permalink to this heading"></a></h2> Once all three of the above files are in place, the extension should build successfully even though it is just a skeleton at this point. <div class="highlight-console notranslate"><div class="highlight"><pre>$ mvn package [INFO] Scanning for projects... [INFO] --------------------------------------------------------------- [INFO] Building guacamole-listener-tutorial 1.5.3 [INFO] --------------------------------------------------------------- ... [INFO] --------------------------------------------------------------- [INFO] BUILD SUCCESS [INFO] --------------------------------------------------------------- [INFO] Total time: 1.297 s [INFO] Finished at: 2017-10-08T13:12:39-04:00 [INFO] Final Memory: 19M/306M [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-listener-tutorial-1.5.3.jar</code>, which can be installed within Guacamole (see <a class="reference internal" href="#custom-listener-installing">Installing the extension</a> at the end of this chapter). It should log event notifications that occur during, for example, authentication attempts. 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="handling-events"> <h2>Handling events<a class="headerlink" href="#handling-events" title="Permalink to this heading"></a></h2> The Guacamole <code class="docutils literal notranslate">Listener</code> interface represents a low-level event handling API. A listener is notified of every event generated by Guacamole. The listener must examine the event type to determine whether the event is of interest, and if so to dispatch the event to the appropriate entry point. The event types that can be produced by Guacamole are described in the <code class="docutils literal notranslate">org.apache.guacamole.net.event</code> package of the guacamole-ext API. In this package you will find several concrete event types as well as interfaces that describe common characteristics of certain of event types. You can use any of these types to distinguish the events received by your listener, and to examine properties of an event of a given type. Suppose we wish to log authentication success and failure events, while ignoring all other event types. The <code class="docutils literal notranslate">AuthenticationSuccessEvent</code> and <code class="docutils literal notranslate">AuthenticationFailureEvent</code> types are used to notify a listener of authentication events. We can simply check whether a received event is of one of these types and, if so, log an appropriate message. <div class="highlight-java notranslate"><div class="highlight"><pre>package org.apache.guacamole.event; import org.apache.guacamole.GuacamoleException; import org.apache.guacamole.net.event.AuthenticationFailureEvent; import org.apache.guacamole.net.event.AuthenticationSuccessEvent; import org.apache.guacamole.net.event.listener.Listener; import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** * A Listener that logs authentication success and failure events. */ public class TutorialListener implements Listener { private static final Logger logger = LoggerFactory.getLogger(TutorialListener.class); @Override public void handleEvent(Object event) throws GuacamoleException { if (event instanceof AuthenticationSuccessEvent) { logger.info("successful authentication for user {}", ((AuthenticationSuccessEvent) event) .getCredentials().getUsername()); } else if (event instanceof AuthenticationFailureEvent) { logger.info("failed authentication for user {}", ((AuthenticationFailureEvent) event) .getCredentials().getUsername()); } } } </pre></div> </div> In our example, we use <code class="docutils literal notranslate">instanceof</code> to check for the two event types of interest to our listener. Once we have identified an event of interest, we can safely cast the event type to access properties of the event. The extension is now complete and can be built as described earlier in <a class="reference internal" href="#custom-listener-building">Building the extension</a> and installed as described below in <a class="reference internal" href="#custom-listener-installing">Installing the extension</a>. </section> <section id="influencing-guacamole-by-event-veto"> <h2>Influencing Guacamole by event veto<a class="headerlink" href="#influencing-guacamole-by-event-veto" title="Permalink to this heading"></a></h2> An implementation of the handleEvent method is permitted to throw any <code class="docutils literal notranslate">GuacamoleException</code>. For certain vetoable event types, throwing a <code class="docutils literal notranslate">GuacamoleException</code> serves to effectively veto the action that resulted in the event notification. See the API documentation for guacamole-ext to learn more about vetoable event types. As an (admittedly contrived) example, suppose we want to prevent a user named “guacadmin” from accessing Guacamole. For whatever reason, we don’t wish to remove or disable the auth database entry for this user. In this case we can use a listener to block this user, preventing access to Guacamole. In the listener, when we get an <code class="docutils literal notranslate">AuthenticationSuccessEvent</code> we can check to see if the user is “guacadmin” and, if so, throw an exception to prevent this user from logging in to Guacamole. <div class="highlight-java notranslate"><div class="highlight"><pre>package org.apache.guacamole.event; import org.apache.guacamole.GuacamoleException; import org.apache.guacamole.GuacamoleSecurityException; import org.apache.guacamole.net.event.AuthenticationFailureEvent; import org.apache.guacamole.net.event.AuthenticationSuccessEvent; import org.apache.guacamole.net.event.listener.Listener; import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** * A Listener that logs authentication success and failure events * and prevents the "guacadmin" user from logging in by throwing * a GuacamoleSecurityException. */ public class TutorialListener implements Listener { private static final Logger logger = LoggerFactory.getLogger(TutorialListener.class); @Override public void handleEvent(Object event) throws GuacamoleException { if (event instanceof AuthenticationSuccessEvent) { final String username = ((AuthenticationSuccessEvent) event) .getCredentials().getUsername(); if ("guacadmin".equals(username)) { logger.warn("user {} has been blocked", username); throw new GuacamoleSecurityException( "User '" + username + "' is currently blocked"); } logger.info("successful authentication for user {}", username); } else if (event instanceof AuthenticationFailureEvent) { logger.info("failed authentication for user {}", ((AuthenticationFailureEvent) event) .getCredentials().getUsername()); } } } </pre></div> </div> If our Guacamole user database contains a user named “guacadmin”, and we build and install this listener extension, we will find that an attempt to log in as this user now results in a message in the UI indicating that the user is blocked. If we examine the Guacamole log, we will see the message indicating that the user was blocked. Because the successful authentication was vetoed, Guacamole sends a subsequent authentication failure notification, which we see logged as well. </section> <section id="installing-the-extension"> <h2>Installing the extension<a class="headerlink" href="#installing-the-extension" title="Permalink 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, copy the <code class="docutils literal notranslate">target/guacamole-listener-tutorial-1.5.3.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 Listener Extension" loaded. </pre></div> </div> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="custom-auth.html" class="btn btn-neutral float-left" title="Custom authentication" accesskey="p" rel="prev"> Previous</a> <a href="writing-you-own-guacamole-app.html" class="btn btn-neutral float-right" title="Writing your own Guacamole application" 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/event-listeners.html (445 lines of code) (raw):