guacConfigGroup
object classWhen connection data is stored within your LDAP directory, each connection is represented by a special type of LDAP group, and permissions related to Guacamole connections can be managed directly with LDAP based on user membership of these groups. Doing this requires schema modifications which add a new object class called guacConfigGroup
.
An LDIF file defining the schema changes in a manner compatible with OpenLDAP is provided by the kcm-guacamole-auth-ldap package within /opt/keeper/share/guacamole-auth-ldap/schema/guacConfigGroup.ldif
. This file can be applied to your OpenLDAP server using the “ldapadd” command:
Once this is done, connections can be defined by creating new guacConfigGroup
objects within the LDAP directory. Each guacConfigGroup
accepts a single guacConfigProtocol attribute, defining the protocol associated with the connection, and any number of guacConfigParameter attributes, each defining a connection parameter name/value pair. Users that should have access to the connection must be added as members of the guacConfigGroup
using the member attribute.
For example, a connection accessible to two users which uses VNC to connect to localhost at port 5900 with the password “secret” could be defined with the following LDIF file:
To read connection data from LDAP, Guacamole’s main configuration file, modify the /etc/kcm-setup/docker-compose.yml
file.
The base DN of all connections defined within LDAP must be specified using the LDAP_CONFIG_BASE_DN
property. This base DN should be the DN of the portion of the LDAP directory whose subtree contains all Guacamole connections accessible via LDAP. Only connections defined within the subtree of this base DN will be visible.
The EXTENSION_PRIORITY
property specifies the order that extensions should be loaded relative to each other. In the following example, all other extensions take priority over LDAP:
To control group membership using LDAP, modify the /etc/kcm-setup/docker-compose.yml
file.
It is also possible grant entire groups access to connections using the seeAlso attribute. This attribute is a standard LDAP attribute, and will be taken into account by Guacamole if the LDAP_GROUP_BASE_DN
property is defined. This property defines the root of the subtree containing all groups which may apply to Guacamole users authenticated using LDAP:
Instructions for authenticating users with LDAP
Keeper Connection Manager provides support for LDAP authentication.
The image keeper/guacamole
can be modified to support LDAP using environmental variables. See the LDAP_* variables defined in the documentation.
If you installed Keeper Connection Manager using the Docker Install method, this does not come preconfigured with LDAP support. The instructions for activating LDAP are below:
(1) On the local instance, stop the containers.
Auto Docker Install:
Docker Compose Install:
(2) Edit the docker-compose file
Using the simple or custom docker method requires modification of docker-compose.yml file to add LDAP support. As root, edit your docker-compose.yml
file and find the "guacamole
" section.
Notes:
Replace "https://glyptodon.lurey.com" in 2 spots with your Keeper Connection Manager login URL
(3) Restart the containers
Simple Install:
The containers should restart after the upgrade. If not run:
Custom Install:
Configuration is complete.
If you require the use of a custom Root Certificate for your LDAP server, you can volume mount the file /etc/pki/ca-trust/extracted/java/cacerts in your Docker Compose to override this certificate in the guacamole docker container.
Import the certificate into a Java truststore using "keytool".
Volume mount the cacerts file to your target guacamole docker container
When reading data from multiple authentication methods, Guacamole compares the unique identifiers of users (usernames) and groups to determine identity. This means that user accounts from different authentication systems will be automatically combined by Guacamole upon successful authentication as long as those user accounts have the same username, and group memberships will take effect across authentication systems so long as the unique names of those groups match.
For a user known to exist within LDAP, that user can be granted permissions to connections within the database by logging in as the administrative user (by default, “guacadmin”) and creating a corresponding database account having the same username. By leaving the password unspecified for the database account, the user will only be able to log in using LDAP, but will still have access to any associated connections defined within the database.
Rather than having to manually look up users or groups within the LDAP directory, and then manually create those same users and groups within Guacamole, it is possible to set up administrative user accounts which can already see and manage available LDAP objects. This streamlines the administrative process, reducing the number of users which must be manually created to one.
To see LDAP objects within Guacamole’s administrative interface, one of the following tasks must be performed:
An administrative user within the Guacamole database, such as the default “guacadmin” user, must be manually created within LDAP with the same username and with sufficient privileges to query all Guacamole users and groups defined within LDAP.
An administrative user must be manually created within Guacamole having the same username as an LDAP user with sufficient privileges to query all Guacamole users and groups defined within LDAP.
Because a Guacamole user created as defined above would have access to LDAP users and groups, database users and groups, and database connections, all of this data will be unified within the same administrative interface within Guacamole. The user will be able to grant LDAP users and groups access to connections within the database to just as they would if only the database were in use.
Multiple LDAP Servers with KCM
If your Active Directory or LDAP deployment spans multiple servers, Guacamole can be configured to use each of your LDAP servers using ldap-servers.yml
, a configuration file similar to guacamole.properties
and located within /etc/guacamole
. When a user authenticates with a Guacamole instance configured to use multiple LDAP servers, each configured LDAP server is tried, in order, until authentication succeeds. Authentication fails only if none of the defined LDAP servers accept the user's provided credentials.
When ldap-servers.yml
is used, the values within guacamole.properties
still have meaning, but instead serve as defaults for the LDAP servers defined in ldap-servers.yml
.
ldap-servers.yml
For example, a simple ldap-servers.yml
that defines two LDAP servers that may be used to authenticate users would contain the following:
When a user attempts to log in, Guacamole will attempt to authenticate the user against the first defined LDAP server (server1.example.net
). If that fails, Guacamole will proceed with the next (server2.example.net
), and so on. Only if authentication fails against all defined LDAP servers will authentication against LDAP fail overall.
Since the only property that varies between the two servers in the above example is the hostname, and since guacamole.properties
serves as the source of default values when ldap-servers.yml
is used, the configuration details common to all servers would be better specified within guacamole.properties
:
The contents of ldap-servers.yml
can then be reduced to only the hostnames:
For example, to define two LDAP servers covering distinct domains, splitting usage of those LDAP servers by whether the user enters their username as "DOMAIN1\username" or "DOMAIN2\username", you would edit your ldap-servers.yml
to contain something like the following:
Each of the LDAP servers defined above will only be used if their corresponding regular expression matches the username specified by the user. Since each of the regular expressions in the above example define a capturing group around the username component of the "DOMAIN\username" format, that portion of the provided username will be used to determine the user's identity. If a user successfully authenticates as "DOMAIN1\myusername", then:
If there are multiple username formats that need to be accepted by each LDAP server, multiple regular expressions may be specified. For example, to match both "MYDOMAIN\myusername" and the UPN-style "myusername@mydomain.example.net" formats, you would specify:
If multiple authentication methods are installed, Guacamole will poll each method as it attempts to authenticate users, and will retrieve connection data from each method once a user has successfully authenticated. This behavior is designed to allow authentication methods to work together, and can be leveraged to authenticate Guacamole users against while storing the connection data for those users within , , or .
If both LDAP and a database authentication method have been configured, Guacamole will automatically attempt to authenticate against both systems whenever a user attempts to log in. The LDAP account will be considered equivalent to the database user if the username is identical, and that user will have access to any data associated with them via the database, as well as any visible objects within the LDAP directory. If that user has permission to query their group memberships within LDAP, and then the user's group membership will also be retrieved upon authentication, and the user will have access to any data associated with those groups via the database.
The ldap-servers.yml
file contains a single YAML list of LDAP servers, with each server definition consisting of a simple list of configuration properties and values. These configuration properties are identical to except that the "ldap-" prefix is omitted.
LDAP servers listed within ldap-servers.yml
may optionally be restricted to only certain users with the "match-usernames
" option. This option accepts both a single string and an array of strings, where each string is a Perl-compatible regular expression. Additionally, if the regular expression includes a capturing group, the contents of the first capturing group will be used as .
The captured portion ("myusername") will be used to.
The captured portion ("myusername") will be used when