Table of Contents
Guacamole's authentication layer is designed to be extendable such that users can integrate Guacamole into existing authentication systems without having to resort to writing their own web application around the Guacamole API.
The web application comes with a default authentication mechanism which uses an XML file to associate users with connections. Plugins for Guacamole that provide LDAP-based authentication or database-based authentication have also been developed.
To demonstrate the principles involved, we will implement a very simple authentication
plugin which associates a single user/password pair with a single connection, with all this
information saved in properties inside the guacamole.properties
file.
In general, all other authentication plugins for Guacamole will use the principles demonstrated here. However, as of Guacamole 0.8.0, the authentication model has been significantly enhanced, and supports more than simply translating a username/password pair into a set of authorized configurations. 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.
When you view any page in Guacamole, whether that be the login screen or the client interface, the page makes an authentication attempt with the web application, sending all available credentials. After entering your username and password, the exact same process occurs, except the web application receives the username and password as well.
The web application handles this authentication attempt by collecting all credentials
available and passing them to a designated class called the "authentication provider".
This class is designated via a property in the guacamole.properties
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.
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.
The bare minimum required for a Guacamole authentication plugin is a
pom.xml file listing guacamole-ext as a dependency, and a
single .java file implementing our stub of an authentication provider.
In our stub, we won't actually do any authentication yet; we'll just universally
reject all authentication attempts by returning null for any
credentials given. You can verify that this is what happens by checking the server
logs.
Example 15.1. Barebones pom.xml required for a simple authentication
plugin.
<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.glyptodon.guacamole</groupId>
<artifactId>guacamole-auth-tutorial</artifactId>
<packaging>jar</packaging>
<version>0.9.0</version>
<name>guacamole-auth-tutorial</name>
<url>http://guac-dev.org/</url>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<build>
<plugins>
<!-- Written for 1.6 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.6</source>
<target>1.6</target>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<!-- Guacamole Java API -->
<dependency>
<groupId>org.glyptodon.guacamole</groupId>
<artifactId>guacamole-common</artifactId>
<version>0.9.0</version>
</dependency>
<!-- Guacamole Extension API -->
<dependency>
<groupId>org.glyptodon.guacamole</groupId>
<artifactId>guacamole-ext</artifactId>
<version>0.9.0</version>
</dependency>
</dependencies>
</project>
We won't need to update this pom.xml throughout the rest of the
tutorial. Even after adding new files, Maven will just find them and compile as
necessary.
Naturally, we need the actual authentication plugin 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
org.glyptodon.guacamole.auth.TutorialAuthenticationProvider.
Example 15.2. A skeleton TutorialAuthenticationProvider
package org.glyptodon.guacamole.auth;
import java.util.Map;
import org.glyptodon.guacamole.GuacamoleException;
import org.glyptodon.guacamole.net.auth.simple.SimpleAuthenticationProvider;
import org.glyptodon.guacamole.net.auth.Credentials;
import org.glyptodon.guacamole.protocol.GuacamoleConfiguration;
public class TutorialAuthenticationProvider extends SimpleAuthenticationProvider {
@Override
public Map<String, GuacamoleConfiguration>
getAuthorizedConfigurations(Credentials credentials)
throws GuacamoleException {
// Do nothing ... yet
return null;
}
}
To conform with Maven, this skeleton file must be placed within
src/main/java/net/sourceforge/guacamole/auth as
TutorialAuthenticationProvider.java.
Notice how simple the authentication provider is. The
AuthenticationProvider interface requires nothing more than a
single getAuthorizedConfigurations() implementation, which must
return a Map of GuacamoleConfiguration
each associated with some arbitrary unique ID. This unique ID will be presented to the
user in the connection list after they log in.
For now, we just return null, which will cause Guacamole to report
an invalid login for every attempt. Note that there is a difference in semantics between
returning an empty map and returning null, 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.
Once we receive credentials, we need to validate those credentials against the
associated properties in guacamole.properties (our source of
authentication information for the sake of this tutorial).
We will define four properties:
- tutorial-user
-
The name of the only user we accept.
- tutorial-password
-
The password we require for the user specified to be authenticated.
- tutorial-protocol
-
The protocol of the configuration this user is authorized to use, which will be sent to guacd when the user logs in and selects their connection.
- tutorial-parameters
-
A comma-delimited list of
name=value
If the username and password match what is stored in the file, we read the
configuration information, store it in a GuacamoleConfiguration,
and return the configuration within a set, telling Guacamole that this user is
authorized but only to access the configurations returned.
Upstream, we always place the properties of authentication providers in their own class, and so we will also do that here in this tutorial, as it keeps things organized.
Example 15.3. TutorialProperties.java, a class containing property
definitions
package org.glyptodon.guacamole.auth;
import org.glyptodon.guacamole.properties.StringGuacamoleProperty;
public class TutorialGuacamoleProperties {
/**
* This class should not be instantiated.
*/
private TutorialGuacamoleProperties() {}
/**
* The only user to allow.
*/
public static final StringGuacamoleProperty TUTORIAL_USER =
new StringGuacamoleProperty() {
@Override
public String getName() { return "tutorial-user"; }
};
/**
* The password required for the specified user.
*/
public static final StringGuacamoleProperty TUTORIAL_PASSWORD =
new StringGuacamoleProperty() {
@Override
public String getName() { return "tutorial-password"; }
};
/**
* The protocol to use when connecting.
*/
public static final StringGuacamoleProperty TUTORIAL_PROTOCOL =
new StringGuacamoleProperty() {
@Override
public String getName() { return "tutorial-protocol"; }
};
/**
* All parameters associated with the connection, as a comma-delimited
* list of name="value"
*/
public static final StringGuacamoleProperty TUTORIAL_PARAMETERS =
new StringGuacamoleProperty() {
@Override
public String getName() { return "tutorial-parameters"; }
};
}
Normally, we would define a new type of GuacamoleProperty to
handle the parsing of the parameters required by TUTORIAL_PARAMETERS,
but for the sake of simplicity, parsing of this parameter will be embedded in the
authentication function later.
You will need to modify your existing guacamole.properties file,
adding each of the above properties to describe one of your available
connections.
Example 15.4. Properties describing a user and connection, as required by this tutorial
# Username and password tutorial-user:tutorialtutorial-password:password# Connection information tutorial-protocol:vnctutorial-parameters:hostname=localhost, port=5900
Once these properties and their accessor class are in place, it's simple enough to
read the properties within getAuthorizedConfigurations() and
authenticate the user based on their username and password.
Example 15.5. Checking the credentials against the properties
@Override
public Map<String, GuacamoleConfiguration>
getAuthorizedConfigurations(Credentials credentials)
throws GuacamoleException {
// Get username
String username = GuacamoleProperties.getRequiredProperty(
TutorialProperties.TUTORIAL_USER
);
// If wrong username, fail
if (!username.equals(credentials.getUsername()))
return null;
// Get password
String password = GuacamoleProperties.getRequiredProperty(
TutorialProperties.TUTORIAL_PASSWORD
);
// If wrong password, fail
if (!password.equals(credentials.getPassword()))
return null;
// Successful login. Return configurations (STUB)
return new HashMap<String, GuacamoleConfiguration>();
}
As is, the authentication provider will work in its current state in that the correct
username and password will authenticate the user, while an incorrect username or
password will not, but we still aren't returning an actual map of configurations. We
need to construct the configuration based on the properties in the
guacamole.properties file after the user has been
authenticated, and return that configuration to the web application.
The only remaining task before we have a fully-functioning authentication provider is
to parse the configuration from the guacamole.properties
file.
Example 15.6. Parsing and returning a GuacamoleConfiguration
@Override
public Map<String, GuacamoleConfiguration>
getAuthorizedConfigurations(Credentials credentials)
throws GuacamoleException {
// Get username
String username = GuacamoleProperties.getRequiredProperty(
TutorialProperties.TUTORIAL_USER
);
// If wrong username, fail
if (!username.equals(credentials.getUsername()))
return null;
// Get password
String password = GuacamoleProperties.getRequiredProperty(
TutorialProperties.TUTORIAL_PASSWORD
);
// If wrong password, fail
if (!password.equals(credentials.getPassword()))
return null;
// Successful login. Return configurations.
Map<String, GuacamoleConfiguration> configs =
new HashMap<String, GuacamoleConfiguration>();
// Create new configuration
GuacamoleConfiguration config = new GuacamoleConfiguration();
// Set protocol specified in properties
config.setProtocol(GuacamoleProperties.getRequiredProperty(
TutorialProperties.TUTORIAL_PROTOCOL
));
// Set all parameters, splitting at commas
for (String parameterValue : GuacamoleProperties.getRequiredProperty(
TutorialProperties.TUTORIAL_PARAMETERS
).split(",\\s*")) {
// Find the equals sign
int equals = parameterValue.indexOf('=');
if (equals == -1)
throw new GuacamoleException("Required equals sign missing");
// Get name and value from parameter string
String name = parameterValue.substring(0, equals);
String value = parameterValue.substring(equals+1);
// Set parameter as specified
config.setParameter(name, value);
}
configs.put("DEFAULT", config);
return configs;
}