Keeper Connection Manager
Search…
Authenticating users with LDAP
Instructions for authenticating users with LDAP
This documentation assumes that you already have access to an LDAP directory, such as OpenLDAP or Active Directory, and that Guacamole has already been installed using Keeper Connection Manager. If you do not already an LDAP directory ready, please set up LDAP before proceeding. If you do not already have Guacamole installed, please see the installation instructions.
This section covers configuring Guacamole to authenticate against a single LDAP server using
guacamole.properties. If planning to use multiple LDAP servers, we highly recommend configuring Guacamole to authenticate against a single LDAP server first, and then migrating to a multi-server configuration once your first LDAP server has been confirmed to be configured correctly. This avoids introducing unnecessary variables too early in the deployment process.If you will be configuring multiple LDAP servers, please see the instructions covering the
ldap-servers.yml configuration file. The configuration options available within ldap-servers.yml are very similar to those documented below except that the YAML format is flexible enough to allow multiple servers to be defined.Simple and Custom Docker Install Method
If you installed Keeper Connection Manager using the Simple Custom 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.
Simple Install:
1
sudo ./ksm-setup.run stop
Copied!
Custom Install:
1
cd /path/to/docker-compose.yml
2
docker-compose stop
Copied!
(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.1
guacamole:
2
image: keeper/guacamole:2
3
environment:
4
ACCEPT_EULA: "Y"
5
GUACD_HOSTNAME: "guacd"
6
MYSQL_HOSTNAME: "db"
7
MYSQL_DATABASE: "guacamole_db"
8
MYSQL_USERNAME: "guacamole_user"
9
MYSQL_PASSWORD: "xxxxxxx"
10
11
# LDAP Connection
12
LDAP_HOSTNAME: "localhost"
13
LDAP_PORT: 389
14
LDAP_ENCRYPTION_METHOD: "none"
15
ADDITIONAL_GUACAMOLE_PROPERTIES: "extension-priority: *, ldap"
16
17
## Optional Settings ##
18
# Mapping Guacamole usernames to LDAP DN’s
19
LDAP_USER_BASE_DN: "ou=people,dc=example,dc=net"
20
LDAP_USERNAME_ATTRIBUTE: "uid"
21
22
# Indirect Username Mapping
23
LDAP_SEARCH_BIND_DN: "cn=someUser,ou=people,dc=example,dc=net"
24
LDAP_SEARCH_BIND_PASSWORD: "some_password"
25
26
# Mapping Guacamole groups to LDAP DN's
27
LDAP_GROUP_BASE_DN: "ou=groups,dc=example,dc=net"
28
LDAP_GROUP_NAME_ATTRIBUTE: "cn"
Copied!
Notes:
- Replace "https://glyptodon.lurey.com" in 2 spots with your Keeper Connection Manager login URL
- If you want ALL users to login with LDAP, then remove the ADDITIONAL_GUACAMOLE_PROPERTIES line. As written, it will give users the choice of password or LDAP login.
Optional settings
Mapping Guacamole usernames to LDAP DN's
Mapping Guacamole groups to LDAP DN’s
(3) Restart the containers
Simple Install:
1
sudo ./ksm-setup.run upgrade
Copied!
The containers should restart after the upgrade. If not run:
1
sudo ./kcm-setup.run start
Copied!
Custom Install:
1
sudo su
2
docker-compose up -d
Copied!
Configuration is complete.
Advanced Linux Install Method
Installing LDAP support for Guacamole
Keeper Connection Manager packages Guacamole’s LDAP support within the kcm-guacamole-auth-ldap package:
1
$ sudo yum install kcm-guacamole-auth-ldap
Copied!
Unlike the MySQL, PostgreSQL, SQL Server and authentication backends, Guacamole’s LDAP support does not require a schema to be applied unless you intend to store connection data within your LDAP directory. If LDAP will be used only to authenticate Guacamole users, no schema modifications need be made, and a database should be used to store connection data.
If you do intend to store connection data within your LDAP directory, you will need to apply the provided schema modifications which create the
guacConfigGroup object class. Be sure to first finish configuring Guacamole for LDAP authentication, and verify that Guacamole can successfully authenticate users against your LDAP directory.
Guacamole’s main configuration file,
/etc/guacamole/guacamole.properties, must be modified to point the LDAP directory:1
$ sudo vi /etc/guacamole/guacamole.properties
Copied!
The
guacamole.properties file provided with Keeper Connection Manager is organized into sections documented with blocks of comments and example properties. The first section which must be modified is marked “LDAP-1” and defines the TCP connection information for the LDAP directory. Uncomment the ldap-hostname property, modifying its value to point to your LDAP server:1
##
2
## [LDAP-1] LDAP TCP connection information
3
##
4
## The TCP connection details of the LDAP server, as well as whether encryption
5
## should be used.
6
##
7
## Legal encryption methods are "none", for unencrypted connections, "ssl"
8
## for LDAP over SSL/TLS (also known as LDAPS), or "starttls" for STARTTLS.
9
##
10
11
#ldap-hostname: localhost
12
#ldap-port: 389
13
#ldap-encryption-method: none
Copied!
By default, Guacamole will connect to your LDAP server without encryption. If your LDAP server uses encryption, you will need to uncomment and set the ldap-encryption-method property to “ssl” for LDAPS (LDAP over SSL/TLS) or “starttls” for STARTTLS.
The default port varies by encryption method, and will be 389 for unencrypted LDAP and STARTTLS, or 636 for LDAPS. If your LDAP server listens on a non-standard port, you will also need to uncomment and modify the ldap-port property.
Mapping Guacamole usernames to LDAP DN’s
To authenticate users using LDAP, Guacamole must translate usernames into their corresponding LDAP DN’s. Depending on the complexity of your LDAP directory, this can be as simple as adding a single attribute to a common base DN, or can involve an LDAP query.
The “LDAP-2” section defines the basic parameters required for either case:
1
##
2
## [LDAP-2] LDAP user / user DN description
3
##
4
## The base DN of all Guacamole users within the LDAP directory, and the
5
## attribute which contains each user's username. If the username attribute
6
## is not part of the DN, a seach DN will need to be provided, as well.
7
##
8
9
#ldap-user-base-dn: ou=people,dc=example,dc=net
10
#ldap-username-attribute: uid
Copied!
The base DN defined by the ldap-user-base-dn property should be the common base shared by all Guacamole users within your LDAP directory, while the attribute which contains the user’s username is defined by ldap-username-attribute. The base DN is always required if LDAP is being used.
Direct username mapping
By default, Guacamole will attempt to derive the user’s DN directly by prepending the username attribute to the base DN. For example, assume a user is attempting to login with the username “someUser”. If the base DN is “ou=people,dc=example,dc=net” and the username attribute is “uid” (the default), then Guacamole will perform the following steps to authenticate the user:
- 1.Prepend the username to the base DN using the “uid” attribute, producing the DN: “uid=someUser,ou=people,dc=example,dc=net”.
- 2.Attempt to bind using the DN “uid=someUser,ou=people,dc=example,dc=net” and the password provided by the user.
- 3.If the bind attempt succeeds, authentication is successful.
Indirect username mapping
For more complex cases, where the user DN is cannot be directly derived by prepending the username attribute, Guacamole can instead issue an LDAP query to determine the user DN. This requires a search DN and password, defined with the ldap-search-bind-dn and ldap-search-bind-password properties respectively, which Guacamole will bind as when performing the query:
1
##
2
## [LDAP-3] LDAP user search DN
3
##
4
## The DN and password of the user to bind as when searching for the DN of each
5
## user attempting to log in. If omitted, the DN of each user will be derived
6
## directly using the user base DN and username attribute.
7
##
8
9
#ldap-search-bind-dn: cn=someUser,ou=people,dc=example,dc=net
10
#ldap-search-bind-password: some_password
Copied!
With the search DN and password configured, Guacamole will perform the following steps to authenticate a user:
- 1.Bind to the LDAP directory using the search DN and password.
- 2.Issue an LDAP query for objects within the subtree of the base DN that contain the user’s username within the defined username attribute.
- 3.If exactly one such object is found, attempt to bind using the DN of that object and the password provided by the user.
- 4.If the bind attempt succeeds, authentication is successful.
Mapping Guacamole groups to LDAP DN’s
Access to connections within Guacamole may be dictated through LDAP user groups via either of two mechanisms:
- 1.Defining connections directly within LDAP using schema modifications and dictating group access using the "seeAlso" attribute.
- 2.
As it is usually preferable to avoid modifying the LDAP schema, mapping LDAP groups to Guacamole groups is recommended. Doing this will require defining the base DN under which all relevant LDAP groups may be found and defining the LDAP attribute that should be used by Guacamole to determine the unique name of the group:
1
##
2
## [LDAP-5] LDAP group / group DN description
3
##
4
## The base DN of all Guacamole groups within the LDAP directory, and the
5
## attribute which should be used by Guacamole to uniquely identify the
6
## group.
7
##
8
## If connections are being stored within LDAP using "guacConfigGroup" objects,
9
## and you wish to control access to these connections via LDAP groups, this is
10
## accomplished using the standard "seeAlso" attribute and the
11
## ldap-group-base-dn property is required.
12
##
13
## If connections are being stored outside of LDAP, such as within a database,
14
## and you wish to control access using LDAP groups, both ldap-group-base-dn
15
## and ldap-group-name-attribute will be required. The group membership of a
16
## user cannot be queried without a base DN, and the unique name to be used by
17
## other parts of Guacamole to represent the group cannot be determined without
18
## the name attribute.
19
##
20
21
#ldap-group-base-dn: ou=groups,dc=example,dc=net
22
#ldap-group-name-attribute: cn
Copied!
Completing installation
Guacamole will generally only load new extensions and reread
guacamole.properties during the startup process. To apply the configuration changes, Guacamole must be restarted:1
$ sudo systemctl restart guacamole
Copied!
Custom Root Certificate
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
For Advanced Linux Install method leveraging the RPMs, this would be accomplished through Red Hat's automated certificate import tooling following this guide.