LDAP Configuration Properties

Advanced configuration properties for LDAP Authentication

The properties listed here are only applicable if LDAP authentication is being used. Support for LDAP authentication is installed using the kcm-guacamole-auth-ldap package. If using the keeper/guacamole Docker image, support for LDAP authentication is instead configured using environment variables.

• TCP connection information

• LDAP user / user DN description

• LDAP user search DN

• LDAP group / group DN description

• Base DN for Guacamole connections (guacConfigGroup)

• LDAP search result limits

• LDAP user attributes

• Custom LDAP search filters

• LDAP aliases and referrals

TCP connection information

The TCP connection details of the LDAP server, as well as whether encryption should be used.

Property name (guacamole.properties)	Property name (ldap-servers.yml)	Default value	Description
ldap-hostname	hostname	localhost	The hostname/address of the LDAP server.
ldap-port	port	389, or 636 for LDAPS	The TCP port that the LDAP server is listening on.
ldap-encryption-method	encryption-method	none	The encryption method to use when communicating with the LDAP server. Valid encryption methods are: none (for unencrypted LDAP) ssl (for LDAP over SSL/TLS, also known as LDAPS) starttls (for STARTTLS)

LDAP user / user DN description

The base DN of all Guacamole users within the LDAP directory, and the attribute which contains each user's username. If the username attribute is not part of the DN, a search DN will need to be provided, as well.

Property name (guacamole.properties)	Property name (ldap-servers.yml)	Default value	Description
ldap-user-base-dn	user-base-dn	N/A	The base DN beneath which all relevant LDAP users may be found. If not using a search DN, this DN must be the common portion of the DN shared by all users to which the username attribute can be added.
ldap-username-attribute	username-attribute	uid	The attribute which contains the user's username. For OpenLDAP, the default value of "uid" is usually correct. For Active Directory, the correct value is typically "sAMAccountName", and a search DN will be needed due to indirect mapping of the username.

LDAP user search DN

The DN and password of the user to bind as when searching for the DN of each user attempting to log in. If omitted, the DN of each user will be derived directly using the user base DN and username attribute.

Property name (guacamole.properties)	Property name (ldap-servers.yml)	Description
ldap-search-bind-dn	search-bind-dn	The DN of the user that Guacamole should bind as when attempting to resolve the DN of an authenticating user (indirect username mapping). If omitted, the DN of each user will be derived directly from the base DN and username attribute. Note that the permissions associated with this account do not affect whether a user can see objects within the LDAP directory. Users, connections, etc. will only be visible to LDAP users if those users are granted permission to see those objects within LDAP.
ldap-search-bind-password	search-bind-password	The password that should be provided when Guacamole binds with the given search DN in order to resolve the DN of an authenticating user.

LDAP group / group DN description

The base DN of all Guacamole user groups within the LDAP directory, and the attribute which contains each group's name. If storing connection information within LDAP, the provided base DN must also contain any groups that may be referenced within "guacConfigGroup" objects using the "seeAlso" attribute.

Property name (guacamole.properties)	Property name (ldap-servers.yml)	Default value	Description
ldap-group-base-dn	group-base-dn	N/A	The base DN beneath which all relevant LDAP groups may be found. This tree will be searched using the user's own credentials to determine their group memberships upon login. If storing connection information within LDAP, this must also be the base DN of the LDAP directory subtree that should be searched for "guacConfigGroup" memberships specified using the "seeAlso" attribute.
ldap-group-name-attribute	group-name-attribute	cn	The attribute which contains the group's name. For most LDAP servers, including Active Directory, the default value of "cn" is usually correct.

Base DN for Guacamole connections (guacConfigGroup)

The base DN for all Guacamole connections defined directly within the LDAP directory using "guacConfigGroup" objects. The LDAP schema files for "guacConfigGroup" objects can be found within /usr/share/guacamole-auth-ldap/schema in both LDIF and .schema format. Note that storing connections directly within the LDAP directory is optional. If connections will not be stored within the directory, this base DN should not be provided.

Property name (guacamole.properties)	Property name (ldap-servers.yml)	Description
ldap-config-base-dn	config-base-dn	The base DN of the LDAP subtree that should be searched for connections stored directly within the directory ("guacConfigGroup" objects). If connections are not being stored within the LDAP directory (no schema changes have been applied), this property should not be specified.

LDAP search result limits

The maximum number of LDAP search results which can be returned by a single query. LDAP searches which exceed this limit will fail.

Property name (guacamole.properties)	Property name (ldap-servers.yml)	Default value	Description
ldap-max-search-results	max-search-results	1000	The maximum number of LDAP search results to retrieve via a single query. By default, LDAP searches are limited to returning a maximum of 1000 entries.

LDAP user attributes

Arbitrary LDAP user attributes may be used to dynamically affect the behavior of connections based on the user accessing them. When a user authenticates with LDAP and subsequently accesses a particular Guacamole connection, the values of these attributes will be made available as parameter tokens and applied to the parameters of the connection. If the attribute has no value for the current user, then the corresponding token is not applied. If the attribute has multiple values, then the first value of the attribute is used.

These attributes must be configured for use as parameter tokens ahead of time by being explicitly listed within /etc/guacamole/guacamole.properties. By default, no LDAP user attributes are made available as parameter tokens.

Property name (guacamole.properties)	Property name (ldap-servers.yml)	Description
ldap-user-attributes	user-attributes	The attribute or attributes to retrieve from the LDAP directory for users that authenticate using LDAP, separated by commas. If specified, the attributes listed here are retrieved from each authenticated user and dynamically applied to the parameters of that user's connections as parameter tokens with the prefix "LDAP_".

When converting an LDAP attribute name into a parameter token name, the name of the attribute is transformed into uppercase with each word separated by underscores, a naming convention referred to as "uppercase with underscores" or "screaming snake case". For example:

LDAP Attribute	Parameter Token
lowercase-with-dashes	${LDAP_LOWERCASE_WITH_DASHES}
CamelCase	${LDAP_CAMEL_CASE}
headlessCamelCase	${LDAP_HEADLESS_CAMEL_CASE}
lettersAndNumbers1234	${LDAP_LETTERS_AND_NUMBERS_1234}
aRANDOM_mixOf-3NAMINGConventions	${LDAP_A_RANDOM_MIX_OF_3_NAMING_CONVENTIONS}

Custom LDAP search filters

The search filter which should be used to retrieve lists of users or groups from the LDAP directory. By default, a filter which matches all objects is used, and the only restriction is given through the relevant base DN. If you need to narrow the lists of users or groups further, the default filter can be overridden.

If overriding a search filter, be sure that the filter is a valid LDAP filter. In particular, an LDAP filter must be enclosed in a matching pair of parenthesis. If unsure whether your filter is valid, or if seeing unexpected results, it can be helpful to verify your filter against your LDAP server using a command-line utility like "ldapsearch".

Property name (guacamole.properties)	Property name (ldap-servers.yml)	Default value	Description
ldap-user-search-filter	user-search-filter	(objectClass=*)	The search filter which should be used to retrieve the list of users from the LDAP directory. If a search DN is used (indirect user mapping), this filter will also restrict the users that can log into Guacamole.
ldap-group-search-filter	group-search-filter	(objectClass=*)	The search filter which should be used to retrieve the list of groups that may be used by other extensions to define permissions.

LDAP aliases and referrals

Whether (and how) Guacamole should follow LDAP aliases or referrals when encountered during an LDAP query. By default, Guacamole will not dereference aliases and will not follow referrals.

Property name (guacamole.properties)	Property name (ldap-servers.yml)	Default value	Description
ldap-dereference-aliases	dereference-aliases	never	The method that Guacamole should use to dereference LDAP aliases, if at all. Legal alias dereferencing modes are: never (do not dereference aliases at all) searching (dereference aliases only after the search base has been found) finding (dereference aliases only when finding the search base) always (dereference aliases in all cases)
ldap-follow-referrals	follow-referrals	false	If set to "true", referrals received from the LDAP directory will be automatically followed. By default, referrals are not followed.
ldap-max-referral-hops	max-referral-hops	5	The maximum number of referrals to follow before aborting an LDAP query. This property only has an effect if LDAP referral following is enabled. If referral following is enabled, the following performed is limited to 5 hops by default.