Table of Contents
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:
An LDAP directory as storage for all authentication data, such as OpenLDAP.
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.
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:
Your users can use their existing usernames and passwords to log into Guacamole.
You can manage Guacamole connections using the same tool that you already use to manage your LDAP directory, such as Apache Directory Studio.
Existing security restrictions can limit visibility/accessibility of Guacamole connections.
Access to connections can easily be granted and revoked, as each connection is represented by a group.
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.jarThe Guacamole LDAP support extension itself, which must be placed in
GUACAMOLE_HOME/extensions.schema/LDAP schema files. An
.ldiffile compatible with OpenLDAP is provided, as well as a.schemafile compliant with RFC-2252. The.schemafile can be transformed into the.ldiffile automatically.
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.schemaA standards-compliant file describing the schema. This file can be used with any LDAP directory compliant with RFC-2252.
guacConfigGroup.ldifAn LDIF file compatible with OpenLDAP. This file was automatically built from the provided
.schemafile 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.
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.ldifadding 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 dndn: 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#
Guacamole extensions are self-contained .jar files which are
located within the GUACAMOLE_HOME/extensions directory. To install
the LDAP authentication extension, you must:
Create the
GUACAMOLE_HOME/extensionsdirectory, if it does not already exist.Remove any existing authentication extensions from
GUACAMOLE_HOME/extensions. Guacamole does not currently support using multiple authentication extensions at the same time.Copy
guacamole-auth-ldap-0.9.7.jarwithinGUACAMOLE_HOME/extensions.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.
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:localhostldap-port:389ldap-user-base-dn:ou=people,dc=example,dc=netldap-username-attribute:uidldap-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.
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.
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.
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.
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 everyguacConfigGroupand can be given only once.- guacConfigParameter
The name and value of a parameter for the specified protocol. This is given as
name=valueThis 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 -Dcn=admin,dc=example,dc=net-W -fexample-connection.ldifEnter 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.