raer2015 Chapter 7. LDAP authertication
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://quac-dev org/releases/.
The LDAP authentication extension is packaged as a . tar.gz file containing
Fipyiguec-devcrgldoclgugdap-auh hilra6r2015 Chapter 7. LDAP authertication
guacamole-auth-1dap-0.9.7.jar
The Guacamole LDAP support extension itself, which must be placed in
GUACAMOLE_HOME/extensions.
schema/
LDAP schema files. An .1di¢ file compatible with OpenLDAP is provided, as well as a . schema file
compliant with RFC-2252. The . schema file can be transformed into the . 1dif 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.1dif
‘An LDIF file compatible with OpenLDAP. This file was automatically built from the provided . schema
file for convenience.
This chapter will cover applying guacConfigGroup.1dif 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 Idapadd utility with the provided
guacConfigGroup. 1dif file:
# Idapadd -Q -¥ EXTERNAL -H ldapi:/// -f schema/guacConfigGroup.1dif
adding new entry "cn=guacConfigGroup, cn=schema,cn=config"
Fipyiguec-devcrgldoclgugdap-auh hilraer2015 Chapter 7. LDAP authertication
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:
# Adapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config dn
dn: cn=schema,cn=config
dn: cn={@)core,cn=schema, cn=config
dn: cn={1}cosine, cn=schema, cn=config
ch={2}nis, cn=schema, cn=config
dn: cn={3)inetorgperson, cn=schema, cn=config
2 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-1dap-@.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 serviet 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
1dap-hostname: localhost
1dap-port: 389
Adap-user-base-dn: ou=people, dc-example,dc=net
ldap-username-attribute: uid
Ldap-config-base-dn: ou=groups, dc=example,de=net
To use Guacamole's LDAP support, you must specify each of the following properties, as shown in the
example above:
Fipyiguec-devcrgldoclgugdap-auh hilra6r2015 Chapter 7. LDAP authertication
Idap-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.
Idap-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.
Idap-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
Idap-username-attribute
The attribute which contains the usemame 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 Idap-user-base-dn is “ou=people,dc=example,dc=net", as in the example above,
and Idap-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, de=ne
Idap-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 serviet 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 serviet 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 Idap-user-base-dn.
The LDAP schema
Fipyiguec-devcrgldoclgugdap-auh hilrae2015 Chapter 7. LOAP authentication
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 concemed, 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 user and user2, you could create an . 1dif file like the following
dn: cn=Example Connection, ou=groups,dce=example, de=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=exanple,dc=net
member: cn=user2,ou=people,de-exanple,de=net
‘The new connection can then be created using the Idapadd utility:
$ ldapadd -x -D cn=admin,dc=example,dc=net -W -f example-connection.1dif
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. 1dif is the name of the . 1dif file you just created.
Fipyiguec-devcrgldoclgugdap-auh hilrae2015 Chapter 7. LOAP authentication
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.
ipuiguse-devorgldocgugldop-auh him