Using Multiple LDAP Servers

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.

Overview of ldap-servers.yml

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 the LDAP properties available within guacamole.properties except that the "ldap-" prefix is omitted.

For example, a simple ldap-servers.yml that defines two LDAP servers that may be used to authenticate users would contain the following:

- hostname: server1.example.net
  user-base-dn: OU=Users,DC=example,DC=net
  username-attribute: sAMAccountName
  search-bind-dn: CN=Guacamole,OU=Services,DC=example,DC=net
  search-bind-password: SomePassword!

- hostname: server2.example.net
  user-base-dn: OU=Users,DC=example,DC=net
  username-attribute: sAMAccountName
  search-bind-dn: CN=Guacamole,OU=Services,DC=example,DC=net
  search-bind-password: SomePassword! 

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.

Abbreviating common LDAP parameters

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:

ldap-user-base-dn: OU=Users,DC=example,DC=net
ldap-username-attribute: sAMAccountName
ldap-search-bind-dn: CN=Guacamole,OU=Services,DC=example,DC=net
ldap-search-bind-password: SomePassword!

The contents of ldap-servers.yml can then be reduced to only the hostnames:

- hostname: server1.example.net
- hostname: server2.example.net

Splitting users across multiple LDAP servers

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 username representing the user's Guacamole identity.

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:

- hostname: domain1.example.net
  user-base-dn: OU=Users,DC=domain1,DC=example,DC=net
  match-usernames: DOMAIN1\\(.*)

- hostname: domain2.example.net
  user-base-dn: OU=Users,DC=domain2,DC=example,DC=net
  match-usernames: DOMAIN2\\(.*)

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:

• The captured portion ("myusername") will be used to identify the user's corresponding account in Guacamole's database.

• The captured portion ("myusername") will be used when mapping the user to their fully-qualified LDAP DN.

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 "[email protected]" formats, you would specify:

- hostname: domain1.example.net
  user-base-dn: OU=Users,DC=domain1,DC=example,DC=net
  match-usernames:
    - DOMAIN1\\(.*)
    - (.*)@domain1\.example\.net

- hostname: domain2.example.net
  user-base-dn: OU=Users,DC=domain2,DC=example,DC=net
  match-usernames:
    - DOMAIN2\\(.*)
    - (.*)@domain2\.example\.net