Guacamole extensions are standard Java .jar files which contain all classes and resources required by the extension, as well as the Guacamole extension manifest. There is no set structure to an extension except that the manifest must be in the root of the archive. Java classes and packages, if any, will be read from the .jar relative to the root, as well.

Beyond this, the semantics and locations associated with all other resources within the extension are determined by the extension manifest alone.

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

{

    "guacamoleVersion" : "0.9.13-incubating",

    "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"
    }

}

<meta name="NAME" content="SELECTOR">

<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>

The configuration of the Guacamole server is exposed through the Environment interface, specifically the LocalEnvironment implementation of this interface. Through Environment, you can access all properties declared within guacamole.properties, determine the proper hostname/port of guacd, and access the contents of GUACAMOLE_HOME.

public class MyProperties {

    public static MY_PROPERTY = new IntegerGuacamoleProperty() {

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

    };

}

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

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

Guacamole's authentication system is driven by authentication providers, which are classes which implement the AuthenticationProvider interface defined by guacamole-ext. When any page within Guacamole is visited, the following process occurs:

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 user-mapping.xml 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 guacamole.properties.

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.

The UserContext 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 UserContext.

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 objects beneath the UserContext is given through Directory classes. These Directory classes are similar to Java collections, but they also embody update and batching 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.

Arbitrary REST resources may be exposed by extensions at the AuthenticationProvider level, if the resource does not require an associated authenticated user, or at the UserContext level, if the resource should be available to authenticated users only. In both cases, the REST resource is provided through implementing the getResource() function, returning an object which is annotated with JAX-RS annotations (JSR 311).

The resource returned by getResource() functions as the root resource, providing access to other resources beneath itself. The root resource for the AuthenticationProvider is exposed at PATH/api/ext/IDENTIFIER, and the root resource for the UserContext is exposed at PATH/api/session/ext/IDENTIFIER, where PATH is the path to which Guacamole has been deployed (typically /guacamole/) and IDENTIFIER is the unique identifier for the AuthenticationProvider, as returned by getIdentifier().

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 AuthenticationProvider level, resources exposed at the UserContext level inherently require the "token" parameter to be present, as it is the sole means of locating the user's session.

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 SystemPermissionSet and ObjectPermissionSet classes which are accessible through the UserContext. These classes also serve as the means for manipulating the permissions granted to a user.

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 getRootConnectionGroup() by the UserContext. 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 getConnectionDirectory() and getConnectionGroupDirectory() of the UserContext.

When a user attempts to use a connection the connect() of the associated Connection 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 InetGuacamoleSocket wrapped within a ConfiguredGuacamoleSocket), and then return a GuacamoleTunnel which controls access to the established socket.

Extensions may maintain historical record of connection use via ConnectionRecord objects, which are exposed both at the Connection level and across all connections via the UserContext. Such record maintenance is optional, and it is expected that most implementations will simply return empty lists.

After a connection has been established, its underlying GuacamoleTunnel can be exposed by a UserContext through the Directory returned by getActiveConnectionDirectory(). The ActiveConnection objects accessible through this Directory are the means by which an administrator may monitor or forcibly terminate another user's connection, ultimately resulting in Guacamole invoking the close() function of the underlying GuacamoleTunnel, and also serve as the basis for screen sharing.

Screen sharing is implemented through the use of SharingProfile objects, exposed through yet another Directory beneath the UserContext. 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 the share menu of the Guacamole menu.

The overall sharing process is as follows: