LDAP Auth

Instructions for authenticating users with LDAP

Keeper Connection Manager provides support for LDAP authentication.

Docker Environmental Variables

The image keeper/guacamole can be modified to support LDAP using environmental variables. See the LDAP_* variables defined in the documentation.

Auto Docker and Docker Compose Install Method

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:

sudo ./kcm-setup.run stop

Docker Compose Install:

cd /path/to/docker-compose.yml
docker-compose stop

(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.

    guacamole:
        image: keeper/guacamole:2
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            MYSQL_HOSTNAME: "db"
            MYSQL_DATABASE: "guacamole_db"
            MYSQL_USERNAME: "guacamole_user"
            MYSQL_PASSWORD: "xxxxxxx"
            
            # LDAP Connection
            LDAP_HOSTNAME: "localhost"
            LDAP_PORT: 389
            LDAP_ENCRYPTION_METHOD: "none"
            
            # Mapping Guacamole usernames to LDAP DN’s
            LDAP_USER_BASE_DN: "ou=people,dc=example,dc=net"
            
            ## Optional Settings ##
            LDAP_USERNAME_ATTRIBUTE: "sAMAccountName"
            
            # Indirect Username Mapping
            LDAP_SEARCH_BIND_DN: "cn=someUser,ou=people,dc=example,dc=net"
            LDAP_SEARCH_BIND_PASSWORD: "some_password"
            
            # Mapping Guacamole groups to LDAP DN's
            LDAP_GROUP_BASE_DN: "ou=groups,dc=example,dc=net"
            LDAP_GROUP_NAME_ATTRIBUTE: "cn"

Optional settings

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.

Add the following options to docker-compose.yml to enable username mapping

            # Mapping Guacamole usernames to LDAP DN’s
            LDAP_USER_BASE_DN: "ou=people,dc=example,dc=net"
            LDAP_USERNAME_ATTRIBUTE: "sAMAccountName"

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:

            # Indirect Username Mapping
            LDAP_SEARCH_BIND_DN: "cn=someUser,ou=people,dc=example,dc=net"
            LDAP_SEARCH_BIND_PASSWORD: "some_password" 

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. Mapping LDAP groups to Guacamole groups and leveraging a database to dictate access.

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:

            # Mapping Guacamole groups to LDAP DN's
            LDAP_GROUP_BASE_DN: "ou=groups,dc=example,dc=net"
            LDAP_GROUP_NAME_ATTRIBUTE: "cn"

If connections are being stored within LDAP using "guacConfigGroup" objects, and you wish to control access to these connections via LDAP groups, this is accomplished using the standard "seeAlso" attribute and the LDAP_GROUP_BASE_DN property is required.

If connections are being stored outside of LDAP, such as within a database, and you wish to control access using LDAP groups, both LDAP_GROUP_BASE_DN and LDAP_GROUP_NAME_ATTRIBUTE will be required. The group membership of a user cannot be queried without a base DN, and the unique name to be used by other parts of Guacamole to represent the group cannot be determined without the name attribute.

(3) Restart the containers

Simple Install:

sudo ./kcm-setup.run upgrade

The containers should restart after the upgrade. If not run:

sudo ./kcm-setup.run start

Custom Install:

sudo su
docker-compose up -d

Configuration is complete.

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