| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 7. LDAP authentication</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="jdbc-auth.html" title="Chapter 6. Database authentication" /><link rel="next" href="duo-auth.html" title="Chapter 8. Duo two-factor authentication" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> |
| </head><body> |
| <!-- CONTENT --> |
| |
| <div id="page"><div id="content"> |
| <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 7. LDAP authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="jdbc-auth.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="duo-auth.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="ldap-auth"></a>Chapter 7. LDAP authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="ldap-auth.html#ldap-architecture">How Guacamole uses LDAP</a></span></dt><dt><span class="section"><a href="ldap-auth.html#ldap-downloading">Downloading the LDAP extension</a></span></dt><dt><span class="section"><a href="ldap-auth.html#ldap-schema-changes">Preparing your LDAP directory (optional)</a></span></dt><dd><dl><dt><span class="section"><a href="ldap-auth.html#idm46420849398608">Applying the schema changes to OpenLDAP</a></span></dt></dl></dd><dt><span class="section"><a href="ldap-auth.html#ldap-and-database">Associating LDAP with a database</a></span></dt><dt><span class="section"><a href="ldap-auth.html#installing-ldap-auth">Installing LDAP authentication</a></span></dt><dd><dl><dt><span class="section"><a href="ldap-auth.html#guac-ldap-config">Configuring Guacamole for LDAP</a></span></dt><dt><span class="section"><a href="ldap-auth.html#idm46420847197056">Completing the installation</a></span></dt></dl></dd><dt><span class="section"><a href="ldap-auth.html#ldap-auth-schema">The LDAP schema</a></span></dt><dd><dl><dt><span class="section"><a href="ldap-auth.html#idm46420848077040">Users</a></span></dt><dt><span class="section"><a href="ldap-auth.html#idm46420848075728">Connections and parameters</a></span></dt></dl></dd></dl></div><a id="idm46420848526848" class="indexterm"></a><p>Guacamole supports LDAP authentication via an extension available from the main project |
| website. This extension allows users and connections to be stored directly within an LDAP |
| directory. If you have a centralized authentication system that uses LDAP, Guacamole's LDAP |
| support can be a good way to allow your users to use their existing usernames and passwords |
| to log into Guacamole.</p><p>To use the LDAP authentication extension, you will need:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>An LDAP directory as storage for all authentication data, such as OpenLDAP.</p></li><li class="listitem"><p>The ability to modify the schema of your LDAP directory.</p></li></ol></div><p>The instructions here assume you already have an LDAP directory installed and working, and |
| do not cover the initial setup of such a directory.</p><div class="important"><h3 class="title">Important</h3><p>This chapter involves modifying the contents of <code class="varname">GUACAMOLE_HOME</code> - |
| the Guacamole configuration directory. If you are unsure where |
| <code class="varname">GUACAMOLE_HOME</code> is located on your system, please consult <a class="xref" href="configuring-guacamole.html" title="Chapter 5. Configuring Guacamole">Chapter 5, <em>Configuring Guacamole</em></a> before proceeding.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ldap-architecture"></a>How Guacamole uses LDAP</h2></div></div></div><p>If the LDAP extension is installed, Guacamole will authenticate users against your |
| LDAP server by attempting a bind as that user. The given username and password will be |
| submitted to the LDAP server during the bind attempt.</p><p>If the bind attempt is successful, the set of available Guacamole connections is |
| queried from the LDAP directory by executing an LDAP query as the bound user. Each |
| Guacamole connection is represented within the directory as a special type of group: |
| <code class="classname">guacConfigGroup</code>. Attributes associated with the group define |
| the protocol and parameters of the connection, and users are allowed access to the |
| connection only if they are associated with that group.</p><p>This architecture has a number of benefits:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Your users can use their existing usernames and passwords to log into |
| Guacamole.</p></li><li class="listitem"><p>You can manage Guacamole connections using the same tool that you already use |
| to manage your LDAP directory, such as <a class="link" href="https://directory.apache.org/studio/" target="_top">Apache Directory |
| Studio</a>.</p></li><li class="listitem"><p>Existing security restrictions can limit visibility/accessibility of Guacamole |
| connections.</p></li><li class="listitem"><p>Access to connections can easily be granted and revoked, as each connection is |
| represented by a group.</p></li></ol></div><div class="important"><h3 class="title">Important</h3><p>Though Guacamole connections can be stored within the LDAP directory, this is not |
| required. Connection data can alternatively be stored within a database like MySQL |
| or PostgreSQL as long as the LDAP username matches the username of the database |
| user. Configuring Guacamole to use a database for authentication or connection |
| storage is covered in <a class="xref" href="jdbc-auth.html" title="Chapter 6. Database authentication">Chapter 6, <em>Database authentication</em></a> and later in this chapter in <a class="xref" href="ldap-auth.html#ldap-and-database" title="Associating LDAP with a database">the section called “Associating LDAP with a database”</a>.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ldap-downloading"></a>Downloading the LDAP extension</h2></div></div></div><p>The LDAP authentication extension is available separately from the main |
| <code class="filename">guacamole.war</code>. The link for this and all other |
| officially-supported and compatible extensions for a particular version of Guacamole are |
| provided on the release notes for that version. You can find the release notes for |
| current versions of Guacamole here: <a class="link" href="http://guacamole.apache.org/releases/" target="_top">http://guacamole.apache.org/releases/</a>.</p><p>The LDAP authentication extension is packaged as a <code class="filename">.tar.gz</code> file |
| containing:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">guacamole-auth-ldap-1.1.0.jar</code></span></dt><dd><p>The Guacamole LDAP support extension itself, which must be placed in |
| <code class="filename">GUACAMOLE_HOME/extensions</code>.</p></dd><dt><span class="term"><code class="filename">schema/</code></span></dt><dd><p>LDAP schema files. An <code class="filename">.ldif</code> file compatible with |
| OpenLDAP is provided, as well as a <code class="filename">.schema</code> file |
| compliant with RFC-2252. The <code class="filename">.schema</code> file can be |
| transformed into the <code class="filename">.ldif</code> file automatically.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ldap-schema-changes"></a>Preparing your LDAP directory (optional)</h2></div></div></div><p>Although your LDAP directory already provides a means of storing and authenticating |
| users, Guacamole also needs storage of connection configuration data, such as hostnames |
| and ports, and a means of associating users with connections that they should have |
| access to. You can do this either through modifying the LDAP directory schema, or |
| through using a database like MySQL or PostgreSQL. If you do not wish to use the LDAP |
| directory for connection storage, skip ahead to <a class="xref" href="ldap-auth.html#ldap-and-database" title="Associating LDAP with a database">the section called “Associating LDAP with a database”</a>.</p><p>If you wish to store connection data directly within the LDAP directory, the required |
| modifications to the LDAP schema are made through applying one of the provided schema |
| files. These schema files define an additional object class, |
| <code class="classname">guacConfigGroup</code>, which contains all configuration information |
| for a particular connection, and can be associated with arbitrarily-many users and |
| groups. Each connection defined by a <code class="classname">guacConfigGroup</code> will be |
| accessible only by users who are members of that group (specified with the |
| <span class="property">member</span> attribute), or who are members of associated groups |
| (specified with the <span class="property">seeAlso</span> attribute).</p><div class="important"><h3 class="title">Important</h3><p>The instructions given for applying the Guacamole LDAP schema changes are specific |
| to OpenLDAP, but other LDAP implementations, including Active Directory, will have |
| their own methods for updating the schema.</p><p>If you are not using OpenLDAP, a standards-compliant schema file is provided that |
| can be used to update the schema of any LDAP directory supporting RFC-2252. Please |
| consult the documentation of your LDAP directory to determine how such schema |
| changes can be applied.</p></div><p>The schema files are located within the <code class="filename">schema/</code> directory of the |
| archive containing the LDAP extension. You will only need one of these files:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">guacConfigGroup.schema</code></span></dt><dd><p>A standards-compliant file describing the schema. This file can be used |
| with any LDAP directory compliant with RFC-2252.</p></dd><dt><span class="term"><code class="filename">guacConfigGroup.ldif</code></span></dt><dd><p>An LDIF file compatible with OpenLDAP. This file was automatically built |
| from the provided <code class="filename">.schema</code> file for convenience.</p></dd></dl></div><p>This chapter will cover applying <code class="filename">guacConfigGroup.ldif</code> to an |
| OpenLDAP server. If you are not using OpenLDAP, your LDAP server should provide |
| documentation for modifying its schema. If this is the case, please consult the |
| documentation of your LDAP server before proceeding.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm46420849398608"></a>Applying the schema changes to OpenLDAP</h3></div></div></div><p>Schema changes to OpenLDAP are applied using the <span class="command"><strong>ldapadd</strong></span> |
| utility with the provided <code class="filename">guacConfigGroup.ldif</code> file:</p><div class="informalexample"><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>ldapadd -Q -Y EXTERNAL -H ldapi:/// -f schema/guacConfigGroup.ldif</code></strong> |
| <code class="computeroutput">adding new entry "cn=guacConfigGroup,cn=schema,cn=config" |
| </code> |
| <code class="prompt">#</code></pre></div><p>If the <code class="classname">guacConfigGroup</code> object was added successfully, you |
| should see output as above. You can confirm the presence of the new object class |
| using <span class="command"><strong>ldapsearch</strong></span>:</p><div class="informalexample"><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config dn</code></strong> |
| <code class="computeroutput">dn: cn=schema,cn=config |
| |
| dn: cn={0}core,cn=schema,cn=config |
| |
| dn: cn={1}cosine,cn=schema,cn=config |
| |
| dn: cn={2}nis,cn=schema,cn=config |
| |
| dn: cn={3}inetorgperson,cn=schema,cn=config |
| |
| dn: cn={4}guacConfigGroup,cn=schema,cn=config |
| </code> |
| <code class="prompt">#</code></pre></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ldap-and-database"></a>Associating LDAP with a database</h2></div></div></div><p>If you install both the LDAP authentication as well as support for a database |
| (following the instructions in <a class="xref" href="jdbc-auth.html" title="Chapter 6. Database authentication">Chapter 6, <em>Database authentication</em></a>), Guacamole will |
| automatically attempt to authenticate against both systems whenever a user attempts to |
| log in. In addition to any visible objects within the LDAP directory, that user will |
| have access to any data associated with their account in the database, as well as any |
| data associated with user groups that they belong to. LDAP user accounts and groups will |
| be considered equivalent to database users and groups if their unique names are |
| identical, as determined by the attributes given for <a class="link" href="ldap-auth.html#guac-ldap-config" title="Configuring Guacamole for LDAP">the <span class="property">ldap-username-attribute</span> and |
| <span class="property">ldap-group-name-attribute</span> properties</a>.</p><p>Data can be manually associated with LDAP user accounts or groups by creating |
| corresponding users or groups within the database which each have the same names. As |
| long as the names are identical, a successful login attempt against LDAP will be trusted |
| by the database authentication, and that user's associated data will be visible.</p><p>If an administrator account (such as the default <code class="systemitem">guacadmin</code> |
| user provided with the database authentication) has a corresponding user in the LDAP |
| directory with permission to read other LDAP users and groups, the Guacamole |
| administrative interface will include them in the lists presented to the administrator, |
| and will allow connections from the database to be associated with those users or groups |
| directly.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing-ldap-auth"></a>Installing LDAP authentication</h2></div></div></div><p>Guacamole extensions are self-contained <code class="filename">.jar</code> files which are |
| located within the <code class="filename">GUACAMOLE_HOME/extensions</code> directory. To install |
| the LDAP authentication extension, you must:</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Create the <code class="filename">GUACAMOLE_HOME/extensions</code> directory, if it |
| does not already exist.</p></li><li class="step"><p>Copy <code class="filename">guacamole-auth-ldap-1.1.0.jar</code> within |
| <code class="filename">GUACAMOLE_HOME/extensions</code>.</p></li><li class="step"><p>Configure Guacamole to use LDAP authentication, as described below.</p></li></ol></div><div class="important"><h3 class="title">Important</h3><p>You will need to restart Guacamole by restarting your servlet container in order |
| to complete the installation. Doing this will disconnect all active users, so be |
| sure that it is safe to do so prior to attempting installation. If you do not |
| configure the LDAP authentication properly, Guacamole will not start up again until |
| the configuration is fixed.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guac-ldap-config"></a>Configuring Guacamole for LDAP</h3></div></div></div><a id="idm46420847161760" class="indexterm"></a><a id="idm46420847160864" class="indexterm"></a><p>Additional properties may be added to <code class="filename">guacamole.properties</code> to |
| describe how your LDAP directory is organized and how Guacamole should connect (and |
| bind) to your LDAP server. Among these properties, only the |
| <span class="property">ldap-user-base-dn</span> property is required:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">ldap-hostname</span></span></dt><dd><p>The hostname of your LDAP server. If omitted, "localhost" will be used |
| by default. You will need to use a different value if your LDAP server |
| is located elsewhere.</p></dd><dt><span class="term"><span class="property">ldap-port</span></span></dt><dd><p>The port your LDAP server listens on. If omitted, the standard LDAP or |
| LDAPS port will be used, depending on the encryption method specified |
| with <span class="property">ldap-encryption-method</span> (if any). Unencrypted |
| LDAP uses the standard port of 389, while LDAPS uses port 636. Unless |
| you manually configured your LDAP server to do otherwise, your LDAP |
| server probably listens on port 389.</p></dd><dt><span class="term"><span class="property">ldap-encryption-method</span></span></dt><dd><p>The encryption mechanism that Guacamole should use when communicating |
| with your LDAP server. Legal values are "none" for unencrypted LDAP, |
| "ssl" for LDAP over SSL/TLS (commonly known as LDAPS), or "starttls" for |
| STARTTLS. If omitted, encryption will not be used.</p><p>If you do use encryption when connecting to your LDAP server, you will |
| need to ensure that its certificate chain can be verified using the |
| certificates in Java's trust store, often referred to as |
| <code class="filename">cacerts</code>. If this is not the case, you will need |
| to use Java's <span class="command"><strong>keytool</strong></span> utility to either add the |
| necessary certificates or to create a new trust store containing those |
| certificates.</p><p>If you will be using your own trust store and not the default |
| <code class="filename">cacerts</code>, you will need to specify the full path |
| to that trust store using the system property |
| <span class="property">javax.net.ssl.trustStore</span>. Note that this is a |
| system property and <span class="emphasis"><em>not</em></span> a Guacamole property; it |
| must be specified when starting the JVM using the <code class="option">-D</code> |
| option. Your servlet container will provide some means of specifying |
| startup options for the JVM.</p></dd><dt><span class="term"><span class="property">ldap-max-search-results</span></span></dt><dd><p>The maximum number of search results that can be returned by a single |
| LDAP query. LDAP queries which exceed this maximum will fail. |
| <span class="emphasis"><em>This property is optional.</em></span> If omitted, each |
| LDAP query will be limited to a maximum of 1000 results.</p></dd><dt><span class="term"><span class="property">ldap-search-bind-dn</span></span></dt><dd><p>The DN (Distinguished Name) of the user to bind as when authenticating |
| users that are attempting to log in. If specified, Guacamole will query |
| the LDAP directory to determine the DN of each user that logs in. If |
| omitted, each user's DN will be derived directly using the base DN |
| specified with <span class="property">ldap-user-base-dn</span>.</p></dd><dt><span class="term"><span class="property">ldap-search-bind-password</span></span></dt><dd><p>The password to provide to the LDAP server when binding as |
| <span class="property">ldap-search-bind-dn</span> to authenticate other |
| users. This property is only used if |
| <span class="property">ldap-search-bind-dn</span> is specified. If omitted, |
| but <span class="property">ldap-search-bind-dn</span> is specified, Guacamole |
| will attempt to bind with the LDAP server without a password.</p></dd><dt><span class="term"><span class="property">ldap-user-base-dn</span></span></dt><dd><p>The base of the DN for all Guacamole users. <span class="emphasis"><em>This property is |
| absolutely required in all cases.</em></span> All Guacamole users |
| must be descendents of this base DN.</p><p>If a search DN is provided (via |
| <span class="property">ldap-search-bind-dn</span>), then Guacamole users need |
| only be somewhere within the subtree of the specified user base |
| DN.</p><p>If a search DN <span class="emphasis"><em>is not</em></span> provided, then all |
| Guacamole users must be <span class="emphasis"><em>direct descendents</em></span> of this |
| base DN, as the base DN will be appended to the username to derive the |
| user's DN. For example, if <span class="property">ldap-user-base-dn</span> is |
| "<code class="systemitem">ou=people,dc=example,dc=net</code>", and |
| <span class="property">ldap-username-attribute</span> is |
| "<span class="property">uid</span>", then a person attempting to login as |
| "<code class="systemitem">user</code>" would be mapped to the following |
| full DN: |
| "<code class="systemitem">uid=user,ou=people,dc=example,dc=net</code>".</p></dd><dt><span class="term"><span class="property">ldap-username-attribute</span></span></dt><dd><p>The attribute or attributes which contain the username within all |
| Guacamole user objects in the LDAP directory. Usually, and by default, |
| this will simply be "<span class="property">uid</span>". If your LDAP directory |
| contains users whose usernames are dictated by different attributes, |
| multiple attributes can be specified here, separated by commas, but |
| beware: <span class="emphasis"><em>doing so requires that a search DN be provided with |
| <span class="property">ldap-search-bind-dn</span></em></span>.</p><p>If a search DN <span class="emphasis"><em>is not</em></span> provided, then the single |
| username attribute specified here will be used together with the user |
| base DN to directly derive the full DN of each user. For example, if |
| <span class="property">ldap-user-base-dn</span> is |
| "<code class="systemitem">ou=people,dc=example,dc=net</code>", and |
| <span class="property">ldap-username-attribute</span> is |
| "<span class="property">uid</span>", then a person attempting to login as |
| "<code class="systemitem">user</code>" would be mapped to the following |
| full DN: |
| "<code class="systemitem">uid=user,ou=people,dc=example,dc=net</code>".</p></dd><dt><span class="term"><span class="property">ldap-member-attribute</span></span></dt><dd><p>The attribute which contains the members within all group objects in the |
| LDAP directory. Usually, and by default, this will simply be |
| "<span class="property">member</span>". If your LDAP directory contains groups |
| whose members are dictated by a different attribute, it can be specified |
| here.</p></dd><dt><span class="term"><span class="property">ldap-user-attributes</span></span></dt><dd><p>The attribute or attributes to retrieve from the LDAP directory for |
| the currently logged-in user, 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 |
| <a class="link" href="configuring-guacamole.html#parameter-tokens" title="Parameter tokens">parameter tokens</a> with the |
| prefix "<code class="varname">LDAP_</code>".</p><p>When a user authenticates with LDAP and accesses a particular |
| Guacamole connection, the values of these tokens will be the values of |
| their corresponding attributes at the time of authentication. 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.</p><p>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 "<a class="link" href="https://en.wikipedia.org/wiki/Naming_convention_(programming)#Multiple-word_identifiers" target="_top">screaming snake case</a>". For example:</p><div class="table"><a id="idm46420849362480"></a><p class="title"><strong>Table 7.1. Example LDAP attribute / parameter token conversions</strong></p><div class="table-contents"><table class="table" summary="Example LDAP attribute / parameter token conversions" border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>LDAP Attribute</th><th>Parameter Token</th></tr></thead><tbody><tr><td><code class="varname">lowercase-with-dashes</code></td><td><code class="varname">${LDAP_LOWERCASE_WITH_DASHES}</code></td></tr><tr><td><code class="varname">CamelCase</code></td><td><code class="varname">${LDAP_CAMEL_CASE}</code></td></tr><tr><td><code class="varname">headlessCamelCase</code></td><td><code class="varname">${LDAP_HEADLESS_CAMEL_CASE}</code></td></tr><tr><td><code class="varname">lettersAndNumbers1234</code></td><td><code class="varname">${LDAP_LETTERS_AND_NUMBERS_1234}</code></td></tr><tr><td><code class="varname">aRANDOM_mixOf-3NAMINGConventions</code></td><td><code class="varname">${LDAP_A_RANDOM_MIX_OF_3_NAMING_CONVENTIONS}</code></td></tr></tbody></table></div></div><br class="table-break" /><p>Usage of parameter tokens is discussed in more detail in <a class="xref" href="configuring-guacamole.html" title="Chapter 5. Configuring Guacamole">Chapter 5, <em>Configuring Guacamole</em></a> in <a class="xref" href="configuring-guacamole.html#parameter-tokens" title="Parameter tokens">the section called “Parameter tokens”</a>.</p></dd><dt><span class="term"><span class="property">ldap-user-search-filter</span></span></dt><dd><p>The search filter used to query the LDAP tree for users that can log |
| into and be granted privileges in Guacamole. <span class="emphasis"><em>If this property |
| is omitted the default of "(objectClass=*)" will be used. |
| </em></span></p></dd><dt><span class="term"><span class="property">ldap-config-base-dn</span></span></dt><dd><p>The base of the DN for all Guacamole configurations. <span class="emphasis"><em>This |
| property is optional.</em></span> If omitted, the configurations of |
| Guacamole connections will simply not be queried from the LDAP |
| directory. If specified, this base DN will be used when querying the |
| configurations accessible by a user once they have successfully logged |
| in.</p><p>Each configuration is analogous to a connection. Within Guacamole's |
| LDAP support, each configuration functions as a group, having user |
| members (via the <span class="property">member</span> attribute) and optionally |
| group members (via the <span class="property">seeAlso</span> attribute), where |
| each member of a particular configuration group will have access to the |
| connection defined by that configuration.</p></dd><dt><span class="term"><span class="property">ldap-group-base-dn</span></span></dt><dd><p>The base of the DN for all user groups that may be used by other |
| extensions to define permissions or that may referenced within Guacamole |
| configurations using the standard <span class="property">seeAlso</span> |
| attribute. All groups which will be used to control access to Guacamole |
| configurations must be descendents of this base DN. <span class="emphasis"><em>If this |
| property is omitted, the <span class="property">seeAlso</span> attribute will |
| have no effect on Guacamole configurations.</em></span></p></dd><dt><span class="term"><span class="property">ldap-group-name-attribute</span></span></dt><dd><p>The attribute or attributes which define the unique name of user |
| groups in the LDAP directory. Usually, and by default, this will simply |
| be "<span class="property">cn</span>". If your LDAP directory contains groups |
| whose names are dictated by different attributes, multiple attributes |
| can be specified here, separated by commas.</p></dd><dt><span class="term"><span class="property">ldap-dereference-aliases</span></span></dt><dd><p>Controls whether or not the LDAP connection follows (dereferences) |
| aliases as it searches the tree. Possible values for this property are |
| "never" (the default) so that aliases will never be followed, |
| "searching" to dereference during search operations after the base |
| object is located, "finding" to dereference in order to locate the |
| search base, but not during the actual search, and "always" to always |
| dereference aliases.</p></dd><dt><span class="term"><span class="property">ldap-follow-referrals</span></span></dt><dd><p>This option controls whether or not the LDAP module follow referrals |
| when processing search results from a LDAP search. Referrals can be |
| pointers to other parts of an LDAP tree, or to a different |
| server/connection altogether. This is a boolean parameter, with valid |
| options of "true" or "false." The default is false. When disabled, LDAP |
| referrals will be ignored when encounterd by the Guacamole LDAP client |
| and the client will move on to the next result. When enabled, the LDAP |
| client will follow the referral and process results within the referral, |
| subject to the maximum hops parameter below.</p></dd><dt><span class="term"><span class="property">ldap-max-referral-hops</span></span></dt><dd><p>This option controls the maximum number of referrals that will be |
| processed before the LDAP client refuses to follow any more referrals. |
| The default is 5. If the ldap-follow-referrals property is set to false |
| (the default), this option has no effect. If the ldap-follow-referrals |
| option is set to true, this will limit the depth of referrals followed |
| to the number specified.</p></dd><dt><span class="term"><span class="property">ldap-operation-timeout</span></span></dt><dd><p>This option sets the timeout, in seconds, of any single LDAP |
| operation. The default is 30 seconds. When this timeout is reached LDAP |
| operations will be aborted.</p></dd></dl></div><p>Again, even if the defaults are sufficient for the other properties, <span class="emphasis"><em>you |
| must still specify the <span class="property">ldap-user-base-dn</span> |
| property</em></span>. An absolutely minimal configuration for LDAP authentication |
| will look like the following:</p><pre class="programlisting"># LDAP properties |
| ldap-user-base-dn: <em class="replaceable"><code>ou=people,dc=example,dc=net</code></em></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm46420847197056"></a>Completing the installation</h3></div></div></div><p>Guacamole will only reread <code class="filename">guacamole.properties</code> and load |
| newly-installed extensions during startup, so your servlet container will need to be |
| restarted before the LDAP authentication will take effect. Restart your servlet |
| container and give the new authentication a try.</p><p> |
| </p><div class="important"><h3 class="title">Important</h3><p>You only need to restart your servlet container. <span class="emphasis"><em>You do not need |
| to restart <span class="package">guacd</span></em></span>.</p><p><span class="package">guacd</span> is completely independent of the web application |
| and does not deal with <code class="filename">guacamole.properties</code> or the |
| authentication system in any way. Since you are already restarting the |
| servlet container, restarting <span class="package">guacd</span> as well technically |
| won't hurt anything, but doing so is completely pointless.</p></div><p> |
| </p><p>If Guacamole does not come back online after restarting your servlet container, |
| check the logs. Problems in the configuration of the LDAP extension will prevent |
| Guacamole from starting up, and any such errors will be recorded in the logs of your |
| servlet container. If properly configured, you will be able to log in as any user |
| within the defined <span class="property">ldap-user-base-dn</span>.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ldap-auth-schema"></a>The LDAP schema</h2></div></div></div><a id="idm46420847788464" class="indexterm"></a><p>Guacamole's LDAP support allows users and connections to be managed purely within an |
| LDAP directory defined in <code class="filename">guacamole.properties</code>. This is |
| accomplished with a minimum of changes to the standard LDAP schema - all Guacamole users |
| are traditional LDAP users and share the same mechanism of authentication. The only new |
| type of object required is a representation for Guacamole connections, |
| <code class="classname">guacConfigGroup</code>, which was added to your server's schema |
| during the install process above.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm46420848077040"></a>Users</h3></div></div></div><p>All Guacamole users, as far as the LDAP support is concerned, are LDAP users with |
| standard LDAP credentials. When a user signs in to Guacamole, their username and |
| password will be used to bind to the LDAP server. If this bind operation is |
| successful, the available connections are queried from the directory and the user is |
| allowed in.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm46420848075728"></a>Connections and parameters</h3></div></div></div><p>Each connection is represented by an instance of the |
| <code class="classname">guacConfigGroup</code> object class, an extended version of the |
| standard LDAP <code class="classname">groupOfNames</code>, which provides a protocol and set |
| of parameters. Only members of the <code class="classname">guacConfigGroup</code> will have |
| access to the corresponding connection.</p><p>The <code class="classname">guacConfigGroup</code> object class provides two new |
| attributes in addition to those provided by |
| <code class="classname">groupOfNames</code>:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">guacConfigProtocol</span></span></dt><dd><p>The protocol associated with the connection, such as |
| "<code class="constant">vnc</code>" or "<code class="constant">rdp</code>". This |
| attribute is required for every <code class="classname">guacConfigGroup</code> |
| and can be given only once.</p></dd><dt><span class="term"><span class="property">guacConfigParameter</span></span></dt><dd><p>The name and value of a parameter for the specified protocol. This is |
| given as |
| <code class="code"><em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></code>, |
| where "name" is the name of the parameter, as defined by the |
| documentation for the protocol specified, and "value" is any allowed |
| value for that parameter.</p><p>This attribute can be given multiple times for the same |
| connection.</p></dd></dl></div><p>For example, to create a new VNC connection which connects to "localhost" at port |
| 5900, while granting access to <code class="systemitem">user1</code> and |
| <code class="systemitem">user2</code>, you could create an <code class="filename">.ldif</code> |
| file like the following:</p><div class="informalexample"><pre class="programlisting">dn: cn=Example Connection,ou=groups,dc=example,dc=net |
| objectClass: guacConfigGroup |
| objectClass: groupOfNames |
| cn: Example Connection |
| guacConfigProtocol: vnc |
| guacConfigParameter: hostname=localhost |
| guacConfigParameter: port=5900 |
| guacConfigParameter: password=secret |
| member: cn=user1,ou=people,dc=example,dc=net |
| member: cn=user2,ou=people,dc=example,dc=net</pre></div><p>The new connection can then be created using the <span class="command"><strong>ldapadd</strong></span> |
| utility:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>ldapadd -x -D <em class="replaceable"><code>cn=admin,dc=example,dc=net</code></em> -W -f <em class="replaceable"><code>example-connection.ldif</code></em></code></strong> |
| <code class="computeroutput">Enter LDAP Password: |
| adding new entry "cn=Example Connection,ou=groups,dc=example,dc=net" |
| </code> |
| <code class="prompt">$</code></pre></div><p>Where <code class="systemitem">cn=admin,dc=example,dc=net</code> is an administrator |
| account with permission to create new entries, and |
| <code class="filename">example-connection.ldif</code> is the name of the |
| <code class="filename">.ldif</code> file you just created.</p><p>There is, of course, no need to use only the standard LDAP utilities to create |
| connections and users. There are useful graphical environments for manipulating LDAP |
| directories, such as <a class="link" href="https://directory.apache.org/studio/" target="_top">Apache |
| Directory Studio</a>, which make many of the tasks given above much |
| easier.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="jdbc-auth.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="duo-auth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Database authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 8. Duo two-factor authentication</td></tr></table></div> |
| |
| </div></div> |
| </body></html> |
