| <?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"> |
| <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.</para> |
| <para>The LDAP authentication module will need an LDAP directory as storage for all |
| authentication data, and the instructions here assume you already have an LDAP directory |
| installed and working. The schema-related directions are further specific to the OpenLDAP |
| implementation of LDAP. Other LDAP implementations will have their own methods for updating |
| the schema. For such situations, a standards-compliant file describing the schema required |
| by Guacamole's LDAP support is included.</para> |
| <section xml:id="installing-ldap-auth"> |
| <title>Installing LDAP authentication</title> |
| <para>The LDAP authentication module is not included in the main Guacamole bundle nor is it |
| enabled by default. You must use the download link provided in the downloads section of |
| the main Guacamole site.</para> |
| <para>The downloaded <filename>.tar.gz</filename> file will contain several |
| directories:</para> |
| <variablelist> |
| <varlistentry> |
| <term><filename>lib/</filename></term> |
| <listitem> |
| <para>Contains all <filename>.jar</filename> files required for the LDAP |
| authentication module to work, including the module itself and the LDAP |
| library driving it.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><filename>schema/</filename></term> |
| <listitem> |
| <para>Contains an <filename>.ldif</filename> file which describes the LDAP |
| schema changes as required for an OpenLDAP server, 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> |
| <para>The contents of <filename>lib/</filename> must be copied into the classpath of |
| Guacamole, which is the directory specified by the <property>lib-directory</property> |
| property in <filename>guacamole.properties</filename>. If this property is not |
| specified, simply add it. On Linux servers, |
| <filename>/var/lib/guacamole/classpath</filename> is a good choice, but it can be |
| whatever you like.</para> |
| <para>After copying the files in place, check to make sure all files are present, and there |
| are no conflicts in between multiple versions of <package>guacamole-auth-ldap</package>. |
| The contents should match at least the files shown here:</para> |
| <screen><prompt>$</prompt> ls <replaceable>/var/lib/guacamole/classpath</replaceable> |
| <computeroutput>guacamole-auth-ldap-0.8.0.jar jldap-4.3.jar</computeroutput> |
| <prompt>$</prompt></screen> |
| <para>Each of the <filename>.jar</filename> files above is either the LDAP authentication |
| module itself (<filename>guacamole-auth-ldap-0.8.0.jar</filename>) or a dependency. They |
| must all be placed in Guacamole's <property>lib-directory</property> for the LDAP |
| authentication to work.</para> |
| <section> |
| <title>Configuring Guacamole</title> |
| <indexterm> |
| <primary>configuring LDAP</primary> |
| </indexterm> |
| <indexterm> |
| <primary>LDAP</primary> |
| <secondary>configuration</secondary> |
| </indexterm> |
| <para>Additional properties must be added to <filename>guacamole.properties</filename> |
| for Guacamole to load the LDAP support and for the LDAP support to properly connect |
| to your LDAP server:</para> |
| <programlisting># Auth provider class |
| auth-provider: net.sourceforge.guacamole.net.auth.ldap.LDAPAuthenticationProvider |
| |
| # LDAP properties |
| ldap-hostname: <replaceable>localhost</replaceable> |
| ldap-port: <replaceable>389</replaceable> |
| ldap-user-base-dn: <replaceable>ou=people,dc=example,dc=net</replaceable> |
| ldap-username-attribute: <replaceable>uid</replaceable> |
| ldap-config-base-dn: <replaceable>ou=groups,dc=example,dc=net</replaceable></programlisting> |
| <para>The LDAP support depends on the following properties, as shown in the example |
| above:</para> |
| <variablelist> |
| <varlistentry> |
| <term><property>ldap-hostname</property></term> |
| <listitem> |
| <para>The hostname of your LDAP server. In the example above, this is given |
| as "localhost" - the same machine as the web server hosting Guacamole, |
| but this can be anything.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-port</property></term> |
| <listitem> |
| <para>The port your LDAP server listens on. Unless you altered the |
| configuration somehow, your LDAP server probably listens on the standard |
| port of 389.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-user-base-dn</property></term> |
| <listitem> |
| <para>The base of the DN (Distinguished Name) for all Guacamole users. This |
| will be appended to the username when a user logs in.</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-username-attribute</property></term> |
| <listitem> |
| <para>The attribute which contains the username which is part of the DN for |
| all Guacamole users. Usually, this is <property>uid</property>. This |
| works together with the user base DN to determine the full DN of each |
| user logging in.</para> |
| <para>For example, if the base DN is |
| "<systemitem>ou=people,dc=example,dc=net</systemitem>" (like the |
| example above) and the username attribute is "<property>uid</property>", |
| then a person attempting to login as "<systemitem>user</systemitem>" |
| would effectively bind with the LDAP directory as |
| "<systemitem>uid=user,ou=people,dc=example,dc=net</systemitem>".</para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><property>ldap-config-base-dn</property></term> |
| <listitem> |
| <para>The base of the DN for all Guacamole configurations. Each |
| configuration is analogous to a connection. Within Guacamole's LDAP |
| support, each configuration functions as a group, having user members. A |
| user which is a member of a particular configuration group will have |
| access to that configuration.</para> |
| <para>This base DN will be used when querying all configurations accessible |
| by a user once they have successfully logged in.</para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| <para>With the above properties properly set, Guacamole will connect to your LDAP server |
| after you restart Tomcat (or whatever servlet container you are using). You will |
| still need to install the schema modifications to your LDAP server such that you can |
| create new configurations and associated them with users.</para> |
| </section> |
| <section> |
| <title>Installing the schema</title> |
| <para>Guacamole's LDAP support requires modifications to the standard LDAP schema, adding |
| support for an additional object called <classname>guacConfigGroup</classname>. This |
| object and its use will be explained in more detail later. For now, we must add |
| support for this object to the LDAP directory through the provided schema |
| file.</para> |
| <para>The <filename>schema/</filename> directory contains two files: |
| <filename>guacConfigGroup.schema</filename>, a standards-compliant file |
| describing the schema, and <filename>guacConfigGroup.ldif</filename>, an LDIF file |
| which was automatically generated from the <filename>.schema</filename> file |
| specifically for update the schema of an OpenLDAP server. We will be working with |
| <filename>guacConfigGroup.ldif</filename>. If you are not using OpenLDAP, your |
| LDAP server should provide documentation for modifying its schema.</para> |
| <para>The <classname>guacConfigGroup</classname> object can be created using the |
| <command>ldapadd</command> utility and the provided <filename>.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 the <command>ldapsearch</command> utility:</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-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, which is simply 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 "vnc" or "rdp". |
| 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 Apache Directory Studio, which make many of the tasks given |
| above much easier.</para> |
| </section> |
| </section> |
| </chapter> |
