Chapter 5. 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.

The LDAP authentication module will need an LDAP directory as storage for all authentication data, and the instructions here assume you already have an LDAP directory installed and working. The schema-related directions are further specific to the OpenLDAP implementation of LDAP. Other LDAP implementations will have their own methods for updating the schema. For such situations, a standards-compliant file describing the schema required by Guacamole's LDAP support is included.

Installing LDAP authentication

The LDAP authentication module is not included in the main Guacamole bundle nor is it enabled by default. You must use the download link provided in the downloads section of the main Guacamole site.

The downloaded .tar.gz file will contain several directories:

lib/

Contains all .jar files required for the LDAP authentication module to work, including the module itself and the LDAP library driving it.

schema/

Contains an .ldif file which describes the LDAP schema changes as required for an OpenLDAP server, as well as a .schema file compliant with RFC-2252. The .schema file can be transformed into the .ldif file automatically.

The contents of lib/ must be copied into the classpath of Guacamole, which is the directory specified by the lib-directory property in guacamole.properties. If this property is not specified, simply add it. On Linux servers, /var/lib/guacamole/classpath is a good choice, but it can be whatever you like.

After copying the files in place, check to make sure all files are present, and there are no conflicts in between multiple versions of guacamole-auth-ldap. The contents should match at least the files shown here:

$ ls /var/lib/guacamole/classpath
guacamole-auth-ldap-0.8.0.jar  jldap-4.3.jar
$

Each of the .jar files above is either the LDAP authentication module itself (guacamole-auth-ldap-0.8.0.jar) or a dependency. They must all be placed in Guacamole's lib-directory for the LDAP authentication to work.

Configuring Guacamole

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:

# Auth provider class
auth-provider: net.sourceforge.guacamole.net.auth.ldap.LDAPAuthenticationProvider

# 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

The LDAP support depends on 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, but this can be anything.

ldap-port

The port your LDAP server listens on. Unless you altered the configuration somehow, your LDAP server probably listens on the standard port of 389.

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 which is part of the DN for all Guacamole users. Usually, this is uid. This works together with the user base DN to determine the full DN of each user logging in.

For example, if the base DN is "ou=people,dc=example,dc=net" (like the example above) and the username attribute is "uid", then a person attempting to login as "user" would effectively bind with the LDAP directory as "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. A user which is a member of a particular configuration group will have access to that configuration.

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

With the above properties properly set, Guacamole will connect to your LDAP server after you restart Tomcat (or whatever servlet container you are using). You will still need to install the schema modifications to your LDAP server such that you can create new configurations and associated them with users.

Installing the schema

Guacamole's LDAP support requires modifications to the standard LDAP schema, adding support for an additional object called guacConfigGroup. This object and its use will be explained in more detail later. For now, we must add support for this object to the LDAP directory through the provided schema file.

The schema/ directory contains two files: guacConfigGroup.schema, a standards-compliant file describing the schema, and guacConfigGroup.ldif, an LDIF file which was automatically generated from the .schema file specifically for update the schema of an OpenLDAP server. We will be working with guacConfigGroup.ldif. If you are not using OpenLDAP, your LDAP server should provide documentation for modifying its schema.

The guacConfigGroup object can be created using the ldapadd utility and the provided .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 the ldapsearch utility:

# 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

#

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, which is simply 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.