The Guacamole extension manifest is a single JSON file, guac-manifest.json, 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:

The only absolutely required properties are guacamoleVersion, name, and namespace, as they are used to identify the extension and for compatibility checks. The most minimal guac-manifest.json will look something like this:

{
    "guacamoleVersion" : "0.9.7",
    "name" : "My Extension",
    "namespace" : "my-extension"
}

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 guac-manifest.json for an extension providing theming or branding would be more involved:

{

    "guacamoleVersion" : "0.9.7",

    "name"      : "My Extension",
    "namespace" : "my-extension",

    "css" : [ "theme.css" ],

    "resources" : {
        "images/logo.png"   : "image/png",
        "images/cancel.png" : "image/png",
        "images/delete.png" : "image/png"
    }

}

If your extension requires generic, unstructured configuration parameters, guacamole.properties is a reasonable and simple location for them. The Environment interface provides direct access to guacamole.properties and simple mechanisms for reading and parsing the properties therein. The value of a property can be retrieved calling getProperty(), which will return null or a default value for undefined properties, or getRequiredProperty(), which will throw an exception for undefined properties.

For convenience, guacamole-ext contains several pre-defined property base classes for common types:

To use these types, you must extend the base class, implementing the getName() function to identify your property. Typically, you would declare these properties as static members of some class containing all properties relevant to your extension:

public class MyProperties {

    public static MY_PROPERTY = new IntegerGuacamoleProperty() {

        @Override
        public String getName() { return "my-property"; }

    };

}

Your property can then be retrieved with getProperty() or getRequiredProperty():

Integer value = environment.getProperty(MyProperties.MY_PROPERTY);

If you need more sophisticated parsing, you can also implement your own property types by implementing the GuacamoleProperty interface. The only functions to implement are getName(), which returns the name of the property, and parseValue(), which parses a given string and returns its value.

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 GUACAMOLE_HOME as long as you avoid placing your files in directories reserved for other purposes as described above.

The Environment interface exposes the location of GUACAMOLE_HOME through the getGuacamoleHome() function. This function returns a standard Java File which can then be used to locate other files or directories within GUACAMOLE_HOME:

File myConfigFile = new File(environment.getGuacamoleHome(), "my-config.xml");

The SimpleAuthenticationProvider 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: getAuthorizedConfigurations().

This function is required to return a Map 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 GuacamoleConfiguration (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 SimpleAuthenticationProvider is asked for more advanced operations by the web application, SimpleAuthenticationProvider 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 SimpleAuthenticationProvider.

The UserContext is the root of all operations. It is used to list, create, modify, or delete users and connections, as well as to query available permissions.

The Guacamole web application uses permissions queries against the UserContext to determine what operations to present, but beware that it is up to the UserContext to actually enforce these restrictions. The Guacamole web application will not enforce restrictions on behalf of the UserContext.

The UserContext is the sole means of entry and the sole means of modification available to a logged-in user. If the UserContext refuses to perform an operation (by throwing an exception), the user cannot perform the operation at all.

Access to users and connections is given through Directory classes. These Directory classes are similar to Java collections, but they also embody object update semantics. Objects can be retrieved from a Directory using its get() function and added or removed with add() and remove() respectively, but objects already in the set can also be updated by passing an updated object to its update() function.

An implementation of a Directory can rely on these functions to define the semantics surrounding all operations. The add() function is called only when creating new objects, the update() function is called only when updating an object previously retrieved with get(), and remove() is called only when removing an existing object by its identifier.

When implementing an AuthenticationProvider, you must ensure that the UserContext will only return Directory classes that automatically enforce the permissions associated with all objects and the associated user.

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.

Authentication modules must return Connection objects which each implement a connect() function. When this function is called, the connection must be made if permission is available.

This new separation of concerns makes more sense when you consider that as connecting is an operation on a Connection, access to performing that operation must be restricted through the AuthenticationProvider, and thus must be enforced within the AuthenticationProvider. This separation also opens the door for things like load balancing of connections and restricting concurrent access to connections.

When a connection is made or terminated, it is also the duty of the authentication module to maintain the connection history. Each connection has a corresponding list of ConnectionRecord objects, each of which is associated with a past connection or a currently-active connection. This information will ultimately be exposed to the user as a history list when they view a connection in the management interface or as a simple active user count on the connection, advising the user of existing activity.