Chapter 7. LDAP authentication

Guacamole supports LDAP authentication via an extension available from the main project website. This extension allows users and connections to be stored directly within an LDAP directory. If you have a centralized authentication system that uses LDAP, Guacamole's LDAP support can be a good way to allow your users to use their existing usernames and passwords to log into Guacamole.

To use the LDAP authentication extension, you will need:

  1. An LDAP directory as storage for all authentication data, such as OpenLDAP.

  2. The ability to modify the schema of your LDAP directory.

The instructions here assume you already have an LDAP directory installed and working, and do not cover the initial setup of such a directory.

Important

This chapter involves modifying the contents of GUACAMOLE_HOME - the Guacamole configuration directory. If you are unsure where GUACAMOLE_HOME is located on your system, please consult Chapter 5, Configuring Guacamole before proceeding.

How Guacamole uses LDAP

If the LDAP extension is installed, Guacamole will authenticate users against your LDAP server by attempting a bind as that user. The given username and password will be submitted to the LDAP server during the bind attempt.

If the bind attempt is successful, the set of available Guacamole connections is queried from the LDAP directory by executing an LDAP query as the bound user. Each Guacamole connection is represented within the directory as a special type of group: guacConfigGroup. Attributes associated with the group define the protocol and parameters of the connection, and users are allowed access to the connection only if they are members of that group.

This architecture has a number of benefits:

  1. Your users can use their existing usernames and passwords to log into Guacamole.

  2. You can manage Guacamole connections using the same tool that you already use to manage your LDAP directory, such as Apache Directory Studio.

  3. Existing security restrictions can limit visibility/accessibility of Guacamole connections.

  4. Access to connections can easily be granted and revoked, as each connection is represented by a group.

Downloading the LDAP extension

The LDAP authentication extension is available separately from the main guacamole.war. The link for this and all other officially-supported and compatible extensions for a particular version of Guacamole are provided on the release notes for that version. You can find the release notes for current versions of Guacamole here: http://guac-dev.org/releases/.

The LDAP authentication extension is packaged as a .tar.gz file containing:

guacamole-auth-ldap-0.9.7.jar

The Guacamole LDAP support extension itself, which must be placed in GUACAMOLE_HOME/extensions.

schema/

LDAP schema files. An .ldif file compatible with OpenLDAP is provided, as well as a .schema file compliant with RFC-2252. The .schema file can be transformed into the .ldif file automatically.

Preparing your LDAP directory

Although your LDAP directory already provides a means of storing and authenticating users, Guacamole also needs storage of connection configuration data, such as hostnames and ports, and a means of associating users with connections that they should have access to.

This need for additional connection storage means that the LDAP directory schema must be modified. An additional object, guacConfigGroup, contains all configuration information for a particular connection, and can be associated with arbitrarily-many users. Only users which are members of a connection's group will have access to that connection.

The necessary modifications to the LDAP schema are made through applying one of the provided schema files. This must be done before Guacamole can be used with LDAP.

Important

The instructions given for applying the Guacamole LDAP schema changes are specific to OpenLDAP, but other LDAP implementations, including Active Directory, will have their own methods for updating the schema.

If you are not using OpenLDAP, a standards-compliant schema file is provided that can be used to update the schema of any LDAP directory supporting RFC-2252. Please consult the documentation of your LDAP directory to determine how such schema changes can be applied.

The schema files are located within the schema/ directory of the archive containing the LDAP extension. You will only need one of these files:

guacConfigGroup.schema

A standards-compliant file describing the schema. This file can be used with any LDAP directory compliant with RFC-2252.

guacConfigGroup.ldif

An LDIF file compatible with OpenLDAP. This file was automatically built from the provided .schema file for convenience.

This chapter will cover applying guacConfigGroup.ldif to an OpenLDAP server. If you are not using OpenLDAP, your LDAP server should provide documentation for modifying its schema. If this is the case, please consult the documentation of your LDAP server before proceeding.

Applying the schema changes to OpenLDAP

Schema changes to OpenLDAP are applied using the ldapadd utility with the provided guacConfigGroup.ldif file:

# ldapadd -Q -Y EXTERNAL -H ldapi:/// -f schema/guacConfigGroup.ldif
adding new entry "cn=guacConfigGroup,cn=schema,cn=config"

#

If the guacConfigGroup object was added successfully, you should see output as above. You can confirm the presence of the new object class using ldapsearch:

# ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config dn
dn: cn=schema,cn=config

dn: cn={0}core,cn=schema,cn=config

dn: cn={1}cosine,cn=schema,cn=config

dn: cn={2}nis,cn=schema,cn=config

dn: cn={3}inetorgperson,cn=schema,cn=config

dn: cn={4}guacConfigGroup,cn=schema,cn=config

#

Installing LDAP authentication

Guacamole extensions are self-contained .jar files which are located within the GUACAMOLE_HOME/extensions directory. To install the LDAP authentication extension, you must:

  1. Create the GUACAMOLE_HOME/extensions directory, if it does not already exist.

  2. Remove any existing authentication extensions from GUACAMOLE_HOME/extensions. Guacamole does not currently support using multiple authentication extensions at the same time.

  3. Copy guacamole-auth-ldap-0.9.7.jar within GUACAMOLE_HOME/extensions.

  4. Configure Guacamole to use LDAP authentication, as described below.

Important

You will need to restart Guacamole by restarting your servlet container in order to complete the installation. Doing this will disconnect all active users, so be sure that it is safe to do so prior to attempting installation. If you do not configure the LDAP authentication properly, Guacamole will not start up again until the configuration is fixed.

Configuring Guacamole for LDAP

Additional properties must be added to guacamole.properties for Guacamole to load the LDAP support and for the LDAP support to properly connect to your LDAP server:

# LDAP properties
ldap-hostname:           localhost
ldap-port:               389
ldap-user-base-dn:       ou=people,dc=example,dc=net
ldap-username-attribute: uid
ldap-config-base-dn:     ou=groups,dc=example,dc=net

To use Guacamole's LDAP support, you must specify each of the following properties, as shown in the example above:

ldap-hostname

The hostname of your LDAP server. In the example above, this is given as "localhost" - the same machine as the web server hosting Guacamole. You will need to use a different value if your LDAP server is located elsewhere.

ldap-port

The port your LDAP server listens on. The example above uses the standard port 389. Unless you manually configured your LDAP server to do otherwise, your LDAP server probably listens on port 389 as well.

ldap-user-base-dn

The base of the DN (Distinguished Name) for all Guacamole users. This will be appended to the username when a user logs in.

ldap-username-attribute

The attribute which contains the username and which is part of the DN for all Guacamole users. Usually, this will be "uid". This is used together with the user base DN to derive the full DN of each user logging in.

For example, if ldap-user-base-dn is "ou=people,dc=example,dc=net", as in the example above, and ldap-username-attribute is "uid", then a person attempting to login as "user" would be mapped to the following full DN: "uid=user,ou=people,dc=example,dc=net".

ldap-config-base-dn

The base of the DN for all Guacamole configurations. Each configuration is analogous to a connection. Within Guacamole's LDAP support, each configuration functions as a group, having user members, where each member of a particular configuration group will have access to that configuration.

This base DN will be used when querying the configurations accessible by a user once they have successfully logged in.

Completing the installation

Guacamole will only reread guacamole.properties and load newly-installed extensions during startup, so your servlet container will need to be restarted before the LDAP authentication will take effect. Restart your servlet container and give the new authentication a try.

Important

You only need to restart your servlet container. You do not need to restart guacd.

guacd is completely independent of the web application and does not deal with guacamole.properties or the authentication system in any way. Since you are already restarting the servlet container, restarting guacd as well technically won't hurt anything, but doing so is completely pointless.

If Guacamole does not come back online after restarting your servlet container, check the logs. Problems in the configuration of the LDAP extension will prevent Guacamole from starting up, and any such errors will be recorded in the logs of your servlet container. If properly configured, you will be able to log in as any user within the defined ldap-user-base-dn.

The LDAP schema

Guacamole's LDAP support allows users and connections to be managed purely within an LDAP directory defined in guacamole.properties. This is accomplished with a minimum of changes to the standard LDAP schema - all Guacamole users are traditional LDAP users and share the same mechanism of authentication. The only new type of object required is a representation for Guacamole connections, guacConfigGroup, which was added to your server's schema during the install process above.

Users

All Guacamole users, as far as the LDAP support is concerned, are LDAP users with standard LDAP credentials. When a user signs in to Guacamole, their username and password will be used to bind to the LDAP server. If this bind operation is successful, the available connections are queried from the directory and the user is allowed in.

Connections and parameters

Each connection is represented by an instance of the guacConfigGroup object class, an extended version of the standard LDAP groupOfNames, which provides a protocol and set of parameters. Only members of the guacConfigGroup will have access to the corresponding connection.

The guacConfigGroup object class provides two new attributes in addition to those provided by groupOfNames:

guacConfigProtocol

The protocol associated with the connection, such as "vnc" or "rdp". This attribute is required for every guacConfigGroup and can be given only once.

guacConfigParameter

The name and value of a parameter for the specified protocol. This is given as name=value, where "name" is the name of the parameter, as defined by the documentation for the protocol specified, and "value" is any allowed value for that parameter.

This attribute can be given multiple times for the same connection.

For example, to create a new VNC connection which connects to "localhost" at port 5900, while granting access to user1 and user2, you could create an .ldif file like the following:

dn: cn=Example Connection,ou=groups,dc=example,dc=net
objectClass: guacConfigGroup
objectClass: groupOfNames
cn: Example Connection
guacConfigProtocol: vnc
guacConfigParameter: hostname=localhost
guacConfigParameter: port=5900
guacConfigParameter: password=secret
member: cn=user1,ou=people,dc=example,dc=net
member: cn=user2,ou=people,dc=example,dc=net

The new connection can then be created using the ldapadd utility:

$ ldapadd -x -D cn=admin,dc=example,dc=net -W -f example-connection.ldif
Enter LDAP Password: 
adding new entry "cn=Example Connection,ou=groups,dc=example,dc=net"

$

Where cn=admin,dc=example,dc=net is an administrator account with permission to create new entries, and example-connection.ldif is the name of the .ldif file you just created.

There is, of course, no need to use only the standard LDAP utilities to create connections and users. There are useful graphical environments for manipulating LDAP directories, such as Apache Directory Studio, which make many of the tasks given above much easier.