GUAC-1437: Add required guac-manifest.json to custom auth tutorial. Correct installation process and related information.
Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/commit/c2d68de7 Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/c2d68de7 Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/c2d68de7 Branch: refs/heads/master Commit: c2d68de778e7164fe3e99e76645cb6c17c6c441d Parents: 765fe6f Author: Michael Jumper <[email protected]> Authored: Wed Dec 16 13:54:56 2015 -0800 Committer: Michael Jumper <[email protected]> Committed: Thu Dec 17 13:12:01 2015 -0800 ---------------------------------------------------------------------- src/chapters/custom-auth.xml | 142 +++++++++++++++---- .../src/main/resources/guac-manifest.json | 12 ++ 2 files changed, 125 insertions(+), 29 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/c2d68de7/src/chapters/custom-auth.xml ---------------------------------------------------------------------- diff --git a/src/chapters/custom-auth.xml b/src/chapters/custom-auth.xml index 9134750..22e06b6 100644 --- a/src/chapters/custom-auth.xml +++ b/src/chapters/custom-auth.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter xml:id="custom-authentication" xmlns="http://docbook.org/ns/docbook"; version="5.0" - xml:lang="en" xmlns:xi="http://www.w3.org/2001/XInclude";> +<chapter xml:id="custom-auth" xmlns="http://docbook.org/ns/docbook"; version="5.0" xml:lang="en" + xmlns:xi="http://www.w3.org/2001/XInclude";> <title>Custom authentication</title> <indexterm xmlns:xl="http://www.w3.org/1999/xlink";> <primary>authentication</primary> @@ -11,17 +11,17 @@ integrate Guacamole into existing authentication systems without having to resort to writing their own web application around the Guacamole API.</para> <para>The web application comes with a default authentication mechanism which uses an XML file - to associate users with connections. Plugins for Guacamole that provide LDAP-based + to associate users with connections. Extensions for Guacamole that provide LDAP-based authentication or database-based authentication have also been developed.</para> <para>To demonstrate the principles involved, we will implement a very simple authentication - plugin which associates a single user/password pair with a single connection, with all this - information saved in properties inside the <filename>guacamole.properties</filename> + extension which associates a single user/password pair with a single connection, with all + this information saved in properties inside the <filename>guacamole.properties</filename> file.</para> - <para>In general, all other authentication plugins for Guacamole will use the principles + <para>In general, all other authentication extensions for Guacamole will use the principles demonstrated here. This tutorial demonstrates the simplest way to create an authentication - plugin for Guacamole - an authentication plugin that does not support management of users - and connections via the web interface.</para> - <section xml:id="auth-model"> + extension for Guacamole - an authentication extension that does not support management of + users and connections via the web interface.</para> + <section xml:id="custom-auth-model"> <title>Guacamole's authentication model</title> <para>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 @@ -29,26 +29,26 @@ process occurs, except the web application receives the username and password as well.</para> <para>The web application handles this authentication attempt by collecting all credentials - available and passing them to a designated class called the "authentication provider". - This class is designated via a property in the <filename>guacamole.properties</filename> - file. Given the set of credentials, the specified authentication provider returns a - context object that provides restricted access to other users and connections, if - any.</para> + 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.</para> </section> - <section xml:id="client-plugin-skeleton"> - <title>A Guacamole plugin skeleton</title> + <section xml:id="custom-auth-skeleton"> + <title>A Guacamole extension skeleton</title> <para>For simplicity's sake, and because this is how things are done upstream in the - Guacamole project, we will use Maven to build our plugin.</para> - <para>The bare minimum required for a Guacamole authentication plugin is a - <filename>pom.xml</filename> file listing guacamole-ext as a dependency, and a - single .java file implementing our stub of an authentication provider.</para> + Guacamole project, we will use Maven to build our extension.</para> + <para>The bare minimum required for a Guacamole authentication extension is a + <filename>pom.xml</filename> file listing guacamole-ext as a dependency, a single + .java file implementing our stub of an authentication provider, and a + <filename>guac-manifest.json</filename> file describing the extension and pointing + to our authentication provider class.</para> <para>In our stub, we won't actually do any authentication yet; we'll just universally reject all authentication attempts by returning <varname>null</varname> for any credentials given. You can verify that this is what happens by checking the server logs.</para> <example> <title>Barebones <filename>pom.xml</filename> required for a simple authentication - plugin.</title> + extension.</title> <programlisting><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 @@ -107,8 +107,8 @@ <para>We won't need to update this <filename>pom.xml</filename> throughout the rest of the tutorial. Even after adding new files, Maven will just find them and compile as necessary.</para> - <para>Naturally, we need the actual authentication plugin skeleton code. While you can put - this in whatever file and package you want, for the sake of this tutorial, we will + <para>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 <classname>org.glyptodon.guacamole.auth.TutorialAuthenticationProvider</classname>.</para> <example> @@ -149,8 +149,9 @@ public class TutorialAuthenticationProvider extends SimpleAuthenticationProvider <filename>src/main/java/org/glyptodon/guacamole/auth</filename> as <filename>TutorialAuthenticationProvider.java</filename>.</para> <para>Notice how simple the authentication provider is. The - <classname>AuthenticationProvider</classname> interface requires nothing more than a - unique identifier (we will use "tutorial") and a single + <classname>SimpleAuthenticationProvider</classname> base class simplifies the + <classname>AuthenticationProvider</classname> interface, requiring nothing more than + a unique identifier (we will use "tutorial") and a single <methodname>getAuthorizedConfigurations()</methodname> implementation, which must return a <classname>Map</classname> of <classname>GuacamoleConfiguration</classname> each associated with some arbitrary unique ID. This unique ID will be presented to the @@ -161,9 +162,70 @@ public class TutorialAuthenticationProvider extends SimpleAuthenticationProvider map and returning <varname>null</varname>, 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.</para> + <para>The only remaining piece for the overall skeleton to be complete is a + <filename>guac-manifest.json</filename> file. <emphasis>This file is absolutely + required for all Guacamole extensions.</emphasis> The + <filename>guac-manifest.json</filename> format is described in more detail in <xref + xmlns:xlink="http://www.w3.org/1999/xlink"; linkend="guacamole-ext"/>. 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.</para> + <para>The Guacamole extension format requires that <filename>guac-manifest.json</filename> + be placed in the root directory of the extension <filename>.jar</filename> file. To + accomplish this with Maven, we place it within the + <filename>src/main/resources</filename> directory. Maven will automatically pick it + up during the build and include it within the <filename>.jar</filename>.</para> + <example> + <title>The required <filename>guac-manifest.json</filename></title> + <programlisting>{ + + "guacamoleVersion" : "0.9.9", + + "name" : "Tutorial Authentication Extension", + "namespace" : "guac-auth-tutorial", + + "authProviders" : [ + "org.glyptodon.guacamole.auth.TutorialAuthenticationProvider" + ] + +}</programlisting> + </example> </section> - <section xml:id="user-auth-example"> - <title>Actually authenticating the user</title> + <section xml:id="custom-auth-building"> + <title>Building the extension</title> + <para>Once all three of the above files are in place, the extension will build, and can even + be installed within Guacamole (see <xref xmlns:xlink="http://www.w3.org/1999/xlink"; + linkend="custom-auth-installing"/> 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:</para> + <informalexample> + <screen><prompt>$</prompt> mvn package +<computeroutput>[INFO] Scanning for projects... +[INFO] ------------------------------------------------------------------------ +[INFO] Building guacamole-auth-tutorial 0.9.9 +[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] ------------------------------------------------------------------------</computeroutput> +<prompt>$</prompt></screen> + </informalexample> + <para>Assuming you see the "<computeroutput>BUILD SUCCESS</computeroutput>" message when you + build the extension, there will be a new file, + <filename>target/guacamole-auth-tutorial-0.9.9.jar</filename>, which can be + installed within Guacamole and tested. If you changed the name or version of the project + in the <filename>pom.xml</filename> file, the name of this new <filename>.jar</filename> + file will be different, but it can still be found within + <filename>target/</filename>.</para> + </section> + <section xml:id="custom-auth-config"> + <title>Configuration and authentication</title> <para>Once we receive credentials, we need to validate those credentials against the associated properties in <filename>guacamole.properties</filename> (our source of authentication information for the sake of this tutorial).</para> @@ -334,10 +396,10 @@ public Map<String, GuacamoleConfiguration> <filename>guacamole.properties</filename> file after the user has been authenticated, and return that configuration to the web application.</para> </section> - <section xml:id="parse-conf-example"> + <section xml:id="custom-auth-more-config"> <title>Parsing the configuration</title> <para>The only remaining task before we have a fully-functioning authentication provider is - to parse the configuration from the <filename>guacamole.properties</filename> + to actually parse the configuration from the <filename>guacamole.properties</filename> file.</para> <example> <title>Parsing and returning a <classname>GuacamoleConfiguration</classname></title> @@ -403,5 +465,27 @@ public Map<String, GuacamoleConfiguration> }</programlisting> </example> + <para>The extension is now complete and can be built as described earlier in <xref + xmlns:xlink="http://www.w3.org/1999/xlink"; linkend="custom-auth-building"/>.</para> + </section> + <section xml:id="custom-auth-installing"> + <title>Installing the extension</title> + <para>Guacamole extensions are self-contained <filename>.jar</filename> files which are + installed by being placed within <filename>GUACAMOLE_HOME/extensions</filename>, and + this extension is no different. As described in <xref + xmlns:xlink="http://www.w3.org/1999/xlink"; linkend="configuring-guacamole"/>, + <varname>GUACAMOLE_HOME</varname> is a placeholder used to refer to the directory + that Guacamole uses to locate its configuration files and extensions. Typically, this + will be the <filename>.guacamole</filename> directory within the home directory of the + user running Tomcat.</para> + <para>To install your extension, ensure that the required properties have been added to your + <filename>guacamole.properties</filename>, copy the + <filename>target/guacamole-auth-tutorial-0.9.9.jar</filename> file into + <filename>GUACAMOLE_HOME/extensions</filename> and restart Tomcat. Guacamole will + automatically load your extension, logging an informative message that it has done + so:</para> + <informalexample> + <screen>Extension "Tutorial Authentication Extension" loaded.</screen> + </informalexample> </section> </chapter> http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/c2d68de7/tutorials/guacamole-auth-tutorial/src/main/resources/guac-manifest.json ---------------------------------------------------------------------- diff --git a/tutorials/guacamole-auth-tutorial/src/main/resources/guac-manifest.json b/tutorials/guacamole-auth-tutorial/src/main/resources/guac-manifest.json new file mode 100644 index 0000000..35dff7f --- /dev/null +++ b/tutorials/guacamole-auth-tutorial/src/main/resources/guac-manifest.json @@ -0,0 +1,12 @@ +{ + + "guacamoleVersion" : "0.9.9", + + "name" : "Tutorial Authentication Extension", + "namespace" : "guac-auth-tutorial", + + "authProviders" : [ + "org.glyptodon.guacamole.auth.TutorialAuthenticationProvider" + ] + +}
