| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <chapter xml:id="ldap-auth" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" |
| xmlns:xi="http://www.w3.org/2001/XInclude" |
| xmlns:xlink="http://www.w3.org/1999/xlink"> |
| <title>LDAP authentication</title> |
| <indexterm> |
| <primary>LDAP</primary> |
| </indexterm> |
| <para>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.</para> |
| <para>To use the LDAP authentication extension, you will need:</para> |
| <orderedlist> |
| <listitem> |
| <para>An LDAP directory as storage for all authentication data, such as OpenLDAP.</para> |
| </listitem> |
| <listitem> |
| <para>The ability to modify the schema of your LDAP directory.</para> |
| </listitem> |
| </orderedlist> |
| <para>The instructions here assume you already have an LDAP directory installed and working, and |
| do not cover the initial setup of such a directory.</para> |
| <important> |
| <para>This chapter involves modifying the contents of <varname>GUACAMOLE_HOME</varname> - |
| the Guacamole configuration directory. If you are unsure where |
| <varname>GUACAMOLE_HOME</varname> is located on your system, please consult <xref |
| linkend="configuring-guacamole"/> before proceeding.</para> |
| </important> |
| <section xml:id="ldap-architecture"> |
| <title>How Guacamole uses LDAP</title> |
| <para>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.</para> |
| <para>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: |
| <classname>guacConfigGroup</classname>. 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.</para> |
| <para>This architecture has a number of benefits:</para> |
| <orderedlist> |
| <listitem> |
| <para>Your users can use their existing usernames and passwords to log into |
| Guacamole.</para> |
| </listitem> |
| <listitem> |
| <para>You can manage Guacamole connections using the same tool that you already use |
| to manage your LDAP directory, such as <link |
| xlink:href="https://directory.apache.org/studio/">Apache Directory |
| Studio</link>.</para> |
| </listitem> |
| <listitem> |
| <para>Existing security restrictions can limit visibility/accessibility of Guacamole |
| connections.</para> |
| </listitem> |
| <listitem> |
| <para>Access to connections can easily be granted and revoked, as each connection is |
| represented by a group.</para> |
| </listitem> |
| </orderedlist> |
| <important> |
| <para>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 <xref linkend="jdbc-auth"/> and later in this chapter in <xref |
| linkend="ldap-and-database"/>.</para> |
| </important> |
| </section> |
| <section xml:id="ldap-downloading"> |
| <title>Downloading the LDAP extension</title> |
| <para>The LDAP authentication extension is available separately from the main |
| <filename>guacamole.war</filename>. 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: <link |
| xlink:href="http://guacamole.apache.org/releases/" |
| >http://guacamole.apache.org/releases/</link>.</para> |
| <para>The LDAP authentication extension is packaged as a <filename>.tar.gz</filename> file |
| containing:</para> |
| <variablelist> |
| <varlistentry> |
| <term><filename>guacamole-auth-ldap-1.1.0.jar</filename></term> |
| <listitem> |
| <para>The Guacamole LDAP support extension itself, which must be placed in |
| <filename>GUACAMOLE_HOME/extensions</filename>.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><filename>schema/</filename></term> |
| <listitem> |
| <para>LDAP schema files. An <filename>.ldif</filename> file compatible with |
| OpenLDAP is provided, as well as a <filename>.schema</filename> file |
| compliant with RFC-2252. The <filename>.schema</filename> file can be |
| transformed into the <filename>.ldif</filename> file automatically.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </section> |
| <section xml:id="ldap-schema-changes"> |
| <title>Preparing your LDAP directory (optional)</title> |
| <para>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 <xref linkend="ldap-and-database" |
| />.</para> |
| <para>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, |
| <classname>guacConfigGroup</classname>, which contains all configuration information |
| for a particular connection, and can be associated with arbitrarily-many users and |
| groups. Each connection defined by a <classname>guacConfigGroup</classname> will be |
| accessible only by users who are members of that group (specified with the |
| <property>member</property> attribute), or who are members of associated groups |
| (specified with the <property>seeAlso</property> attribute).</para> |
| <important> |
| <para>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.</para> |
| <para>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.</para> |
| </important> |
| <para>The schema files are located within the <filename>schema/</filename> directory of the |
| archive containing the LDAP extension. You will only need one of these files:</para> |
| <variablelist> |
| <varlistentry> |
| <term><filename>guacConfigGroup.schema</filename></term> |
| <listitem> |
| <para>A standards-compliant file describing the schema. This file can be used |
| with any LDAP directory compliant with RFC-2252.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><filename>guacConfigGroup.ldif</filename></term> |
| <listitem> |
| <para>An LDIF file compatible with OpenLDAP. This file was automatically built |
| from the provided <filename>.schema</filename> file for convenience.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| <para>This chapter will cover applying <filename>guacConfigGroup.ldif</filename> 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.</para> |
| <section> |
| <title>Applying the schema changes to OpenLDAP</title> |
| <para>Schema changes to OpenLDAP are applied using the <command>ldapadd</command> |
| utility with the provided <filename>guacConfigGroup.ldif</filename> file:</para> |
| <informalexample> |
| <screen><prompt>#</prompt> <userinput>ldapadd -Q -Y EXTERNAL -H ldapi:/// -f schema/guacConfigGroup.ldif</userinput> |
| <computeroutput>adding new entry "cn=guacConfigGroup,cn=schema,cn=config" |
| </computeroutput> |
| <prompt>#</prompt></screen> |
| </informalexample> |
| <para>If the <classname>guacConfigGroup</classname> object was added successfully, you |
| should see output as above. You can confirm the presence of the new object class |
| using <command>ldapsearch</command>:</para> |
| <informalexample> |
| <screen><prompt>#</prompt> <userinput>ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config dn</userinput> |
| <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 |
| </computeroutput> |
| <prompt>#</prompt></screen> |
| </informalexample> |
| </section> |
| </section> |
| <section xml:id="ldap-and-database"> |
| <title>Associating LDAP with a database</title> |
| <para>If you install both the LDAP authentication as well as support for a database |
| (following the instructions in <xref linkend="jdbc-auth"/>), 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 <link linkend="guac-ldap-config" |
| >the <property>ldap-username-attribute</property> and |
| <property>ldap-group-name-attribute</property> properties</link>.</para> |
| <para>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.</para> |
| <para>If an administrator account (such as the default <systemitem>guacadmin</systemitem> |
| 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.</para> |
| </section> |
| <section xml:id="installing-ldap-auth"> |
| <title>Installing LDAP authentication</title> |
| <para>Guacamole extensions are self-contained <filename>.jar</filename> files which are |
| located within the <filename>GUACAMOLE_HOME/extensions</filename> directory. To install |
| the LDAP authentication extension, you must:</para> |
| <procedure> |
| <step> |
| <para>Create the <filename>GUACAMOLE_HOME/extensions</filename> directory, if it |
| does not already exist.</para> |
| </step> |
| <step> |
| <para>Copy <filename>guacamole-auth-ldap-1.1.0.jar</filename> within |
| <filename>GUACAMOLE_HOME/extensions</filename>.</para> |
| </step> |
| <step> |
| <para>Configure Guacamole to use LDAP authentication, as described below.</para> |
| </step> |
| </procedure> |
| <important> |
| <para>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.</para> |
| </important> |
| <section xml:id="guac-ldap-config"> |
| <title>Configuring Guacamole for LDAP</title> |
| <indexterm> |
| <primary>configuring LDAP</primary> |
| </indexterm> |
| <indexterm> |
| <primary>LDAP</primary> |
| <secondary>configuration</secondary> |
| </indexterm> |
| <para>Additional properties may be added to <filename>guacamole.properties</filename> to |
| describe how your LDAP directory is organized and how Guacamole should connect (and |
| bind) to your LDAP server. Among these properties, only the |
| <property>ldap-user-base-dn</property> property is required:</para> |
| <variablelist> |
| <varlistentry> |
| <term><property>ldap-hostname</property></term> |
| <listitem> |
| <para>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.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-port</property></term> |
| <listitem> |
| <para>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 <property>ldap-encryption-method</property> (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.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-encryption-method</property></term> |
| <listitem> |
| <para>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.</para> |
| <para>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 |
| <filename>cacerts</filename>. If this is not the case, you will need |
| to use Java's <command>keytool</command> utility to either add the |
| necessary certificates or to create a new trust store containing those |
| certificates.</para> |
| <para>If you will be using your own trust store and not the default |
| <filename>cacerts</filename>, you will need to specify the full path |
| to that trust store using the system property |
| <property>javax.net.ssl.trustStore</property>. Note that this is a |
| system property and <emphasis>not</emphasis> a Guacamole property; it |
| must be specified when starting the JVM using the <option>-D</option> |
| option. Your servlet container will provide some means of specifying |
| startup options for the JVM.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-max-search-results</property></term> |
| <listitem> |
| <para>The maximum number of search results that can be returned by a single |
| LDAP query. LDAP queries which exceed this maximum will fail. |
| <emphasis>This property is optional.</emphasis> If omitted, each |
| LDAP query will be limited to a maximum of 1000 results.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-search-bind-dn</property></term> |
| <listitem> |
| <para>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 <property>ldap-user-base-dn</property>.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-search-bind-password</property></term> |
| <listitem> |
| <para>The password to provide to the LDAP server when binding as |
| <property>ldap-search-bind-dn</property> to authenticate other |
| users. This property is only used if |
| <property>ldap-search-bind-dn</property> is specified. If omitted, |
| but <property>ldap-search-bind-dn</property> is specified, Guacamole |
| will attempt to bind with the LDAP server without a password.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-user-base-dn</property></term> |
| <listitem> |
| <para>The base of the DN for all Guacamole users. <emphasis>This property is |
| absolutely required in all cases.</emphasis> All Guacamole users |
| must be descendents of this base DN.</para> |
| <para>If a search DN is provided (via |
| <property>ldap-search-bind-dn</property>), then Guacamole users need |
| only be somewhere within the subtree of the specified user base |
| DN.</para> |
| <para>If a search DN <emphasis>is not</emphasis> provided, then all |
| Guacamole users must be <emphasis>direct descendents</emphasis> of this |
| base DN, as the base DN will be appended to the username to derive the |
| user's DN. For example, if <property>ldap-user-base-dn</property> is |
| "<systemitem>ou=people,dc=example,dc=net</systemitem>", and |
| <property>ldap-username-attribute</property> is |
| "<property>uid</property>", then a person attempting to login as |
| "<systemitem>user</systemitem>" would be mapped to the following |
| full DN: |
| "<systemitem>uid=user,ou=people,dc=example,dc=net</systemitem>".</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-username-attribute</property></term> |
| <listitem> |
| <para>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 "<property>uid</property>". If your LDAP directory |
| contains users whose usernames are dictated by different attributes, |
| multiple attributes can be specified here, separated by commas, but |
| beware: <emphasis>doing so requires that a search DN be provided with |
| <property>ldap-search-bind-dn</property></emphasis>.</para> |
| <para>If a search DN <emphasis>is not</emphasis> 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 |
| <property>ldap-user-base-dn</property> is |
| "<systemitem>ou=people,dc=example,dc=net</systemitem>", and |
| <property>ldap-username-attribute</property> is |
| "<property>uid</property>", then a person attempting to login as |
| "<systemitem>user</systemitem>" would be mapped to the following |
| full DN: |
| "<systemitem>uid=user,ou=people,dc=example,dc=net</systemitem>".</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-member-attribute</property></term> |
| <listitem> |
| <para>The attribute which contains the members within all group objects in the |
| LDAP directory. Usually, and by default, this will simply be |
| "<property>member</property>". If your LDAP directory contains groups |
| whose members are dictated by a different attribute, it can be specified |
| here.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-user-attributes</property></term> |
| <listitem> |
| <para>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 |
| <link linkend="parameter-tokens">parameter tokens</link> with the |
| prefix "<varname>LDAP_</varname>".</para> |
| <para>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.</para> |
| <para>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 "<link |
| xlink:href="https://en.wikipedia.org/wiki/Naming_convention_(programming)#Multiple-word_identifiers" |
| >screaming snake case</link>". For example:</para> |
| <table frame="all"> |
| <title>Example LDAP attribute / parameter token conversions</title> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <thead> |
| <row> |
| <entry>LDAP Attribute</entry> |
| <entry>Parameter Token</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry><varname>lowercase-with-dashes</varname></entry> |
| <entry><varname>${LDAP_LOWERCASE_WITH_DASHES}</varname></entry> |
| </row> |
| <row> |
| <entry><varname>CamelCase</varname></entry> |
| <entry><varname>${LDAP_CAMEL_CASE}</varname></entry> |
| </row> |
| <row> |
| <entry><varname>headlessCamelCase</varname></entry> |
| <entry><varname>${LDAP_HEADLESS_CAMEL_CASE}</varname></entry> |
| </row> |
| <row> |
| <entry><varname>lettersAndNumbers1234</varname></entry> |
| <entry><varname>${LDAP_LETTERS_AND_NUMBERS_1234}</varname></entry> |
| </row> |
| <row> |
| <entry><varname>aRANDOM_mixOf-3NAMINGConventions</varname></entry> |
| <entry><varname>${LDAP_A_RANDOM_MIX_OF_3_NAMING_CONVENTIONS}</varname></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| <para>Usage of parameter tokens is discussed in more detail in <xref |
| linkend="configuring-guacamole"/> in <xref |
| linkend="parameter-tokens"/>.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-user-search-filter</property></term> |
| <listitem> |
| <para>The search filter used to query the LDAP tree for users that can log |
| into and be granted privileges in Guacamole. <emphasis>If this property |
| is omitted the default of "(objectClass=*)" will be used. |
| </emphasis></para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-config-base-dn</property></term> |
| <listitem> |
| <para>The base of the DN for all Guacamole configurations. <emphasis>This |
| property is optional.</emphasis> 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.</para> |
| <para>Each configuration is analogous to a connection. Within Guacamole's |
| LDAP support, each configuration functions as a group, having user |
| members (via the <property>member</property> attribute) and optionally |
| group members (via the <property>seeAlso</property> attribute), where |
| each member of a particular configuration group will have access to the |
| connection defined by that configuration.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-group-base-dn</property></term> |
| <listitem> |
| <para>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 <property>seeAlso</property> |
| attribute. All groups which will be used to control access to Guacamole |
| configurations must be descendents of this base DN. <emphasis>If this |
| property is omitted, the <property>seeAlso</property> attribute will |
| have no effect on Guacamole configurations.</emphasis></para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-group-name-attribute</property></term> |
| <listitem> |
| <para>The attribute or attributes which define the unique name of user |
| groups in the LDAP directory. Usually, and by default, this will simply |
| be "<property>cn</property>". If your LDAP directory contains groups |
| whose names are dictated by different attributes, multiple attributes |
| can be specified here, separated by commas.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-dereference-aliases</property></term> |
| <listitem> |
| <para>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.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-follow-referrals</property></term> |
| <listitem> |
| <para>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.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-max-referral-hops</property></term> |
| <listitem> |
| <para>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.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-operation-timeout</property></term> |
| <listitem> |
| <para>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.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| <para>Again, even if the defaults are sufficient for the other properties, <emphasis>you |
| must still specify the <property>ldap-user-base-dn</property> |
| property</emphasis>. An absolutely minimal configuration for LDAP authentication |
| will look like the following:</para> |
| <programlisting># LDAP properties |
| ldap-user-base-dn: <replaceable>ou=people,dc=example,dc=net</replaceable></programlisting> |
| </section> |
| <section> |
| <title>Completing the installation</title> |
| <para>Guacamole will only reread <filename>guacamole.properties</filename> 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.</para> |
| <para> |
| <important> |
| <para>You only need to restart your servlet container. <emphasis>You do not need |
| to restart <package>guacd</package></emphasis>.</para> |
| <para><package>guacd</package> is completely independent of the web application |
| and does not deal with <filename>guacamole.properties</filename> or the |
| authentication system in any way. Since you are already restarting the |
| servlet container, restarting <package>guacd</package> as well technically |
| won't hurt anything, but doing so is completely pointless.</para> |
| </important> |
| </para> |
| <para>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 <property>ldap-user-base-dn</property>.</para> |
| </section> |
| </section> |
| <section xml:id="ldap-auth-schema"> |
| <title>The LDAP schema</title> |
| <indexterm> |
| <primary>schema</primary> |
| </indexterm> |
| <para>Guacamole's LDAP support allows users and connections to be managed purely within an |
| LDAP directory defined in <filename>guacamole.properties</filename>. 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, |
| <classname>guacConfigGroup</classname>, which was added to your server's schema |
| during the install process above.</para> |
| <section> |
| <title>Users</title> |
| <para>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.</para> |
| </section> |
| <section> |
| <title>Connections and parameters</title> |
| <para>Each connection is represented by an instance of the |
| <classname>guacConfigGroup</classname> object class, an extended version of the |
| standard LDAP <classname>groupOfNames</classname>, which provides a protocol and set |
| of parameters. Only members of the <classname>guacConfigGroup</classname> will have |
| access to the corresponding connection.</para> |
| <para>The <classname>guacConfigGroup</classname> object class provides two new |
| attributes in addition to those provided by |
| <classname>groupOfNames</classname>:</para> |
| <variablelist> |
| <varlistentry> |
| <term><property>guacConfigProtocol</property></term> |
| <listitem> |
| <para>The protocol associated with the connection, such as |
| "<constant>vnc</constant>" or "<constant>rdp</constant>". This |
| attribute is required for every <classname>guacConfigGroup</classname> |
| and can be given only once.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>guacConfigParameter</property></term> |
| <listitem> |
| <para>The name and value of a parameter for the specified protocol. This is |
| given as |
| <code><replaceable>name</replaceable>=<replaceable>value</replaceable></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.</para> |
| <para>This attribute can be given multiple times for the same |
| connection.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| <para>For example, to create a new VNC connection which connects to "localhost" at port |
| 5900, while granting access to <systemitem>user1</systemitem> and |
| <systemitem>user2</systemitem>, you could create an <filename>.ldif</filename> |
| file like the following:</para> |
| <informalexample> |
| <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</programlisting> |
| </informalexample> |
| <para>The new connection can then be created using the <command>ldapadd</command> |
| utility:</para> |
| <informalexample> |
| <screen><prompt>$</prompt> <userinput>ldapadd -x -D <replaceable>cn=admin,dc=example,dc=net</replaceable> -W -f <replaceable>example-connection.ldif</replaceable></userinput> |
| <computeroutput>Enter LDAP Password: |
| adding new entry "cn=Example Connection,ou=groups,dc=example,dc=net" |
| </computeroutput> |
| <prompt>$</prompt></screen> |
| </informalexample> |
| <para>Where <systemitem>cn=admin,dc=example,dc=net</systemitem> is an administrator |
| account with permission to create new entries, and |
| <filename>example-connection.ldif</filename> is the name of the |
| <filename>.ldif</filename> file you just created.</para> |
| <para>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 <link xlink:href="https://directory.apache.org/studio/">Apache |
| Directory Studio</link>, which make many of the tasks given above much |
| easier.</para> |
| </section> |
| </section> |
| </chapter> |