| <?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-NS Stylesheets V1.78.1" /><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="noauth.html" title="Chapter 8. Disabling 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="noauth.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#idm139795230823360">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#idm139795231508800">Configuring Guacamole for LDAP</a></span></dt><dt><span class="section"><a href="ldap-auth.html#idm139795231528960">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#idm139795231411184">Users</a></span></dt><dt><span class="section"><a href="ldap-auth.html#idm139795231409456">Connections and parameters</a></span></dt></dl></dd></dl></div><a id="idm139795232099376" 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 members of 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://guac-dev.org/releases/" target="_top">http://guac-dev.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-0.9.8.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. Only |
| users which are members of a connection's group will have access to that |
| connection.</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="idm139795230823360"></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 MySQL or PostgreSQL |
| (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. That user will have access to any data associated with them via the database, as |
| well as any visible objects within the LDAP directory. The LDAP account will be |
| considered equivalent to the database user if the username is identical.</p><p>Data can be manually associated with LDAP users by creating corresponding user |
| accounts within the database which each have the same usernames as valid LDAP users. As |
| long as the username is 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 list and read other LDAP users, the Guacamole |
| administrative interface will include LDAP users in the overall user list presented to |
| the administrator, and allow connections from the database to be associated with those |
| users 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>Remove any existing authentication extensions from |
| <code class="filename">GUACAMOLE_HOME/extensions</code>. Guacamole does not currently |
| support using multiple authentication extensions at the same time.</p></li><li class="step"><p>Copy <code class="filename">guacamole-auth-ldap-0.9.8.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="idm139795231508800"></a>Configuring Guacamole for LDAP</h3></div></div></div><a id="idm139795231508048" class="indexterm"></a><a id="idm139795231507152" class="indexterm"></a><p>Additional properties must be added to <code class="filename">guacamole.properties</code> |
| for Guacamole to load the LDAP support and for the LDAP support to properly connect |
| to your LDAP server:</p><pre class="programlisting"># LDAP properties |
| ldap-hostname: <em class="replaceable"><code>localhost</code></em> |
| ldap-port: <em class="replaceable"><code>389</code></em> |
| ldap-user-base-dn: <em class="replaceable"><code>ou=people,dc=example,dc=net</code></em> |
| ldap-username-attribute: <em class="replaceable"><code>uid</code></em> |
| ldap-config-base-dn: <em class="replaceable"><code>ou=groups,dc=example,dc=net</code></em></pre><p>To use Guacamole's LDAP support, you must specify each of the following |
| properties, as shown in the example above:</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. In the example above, this is given |
| as "localhost" - the same machine as the web server hosting Guacamole. |
| 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. The example above uses the |
| standard port 389. Unless you manually configured your LDAP server to do |
| otherwise, your LDAP server probably listens on port 389 as well.</p></dd><dt><span class="term"><span class="property">ldap-user-base-dn</span></span></dt><dd><p>The base of the DN (Distinguished Name) for all Guacamole users. This |
| will be appended to the username when a user logs in.</p></dd><dt><span class="term"><span class="property">ldap-username-attribute</span></span></dt><dd><p>The attribute which contains the username and which is part of the DN |
| for all Guacamole users. Usually, this will be |
| "<span class="property">uid</span>". This is used together with the user base DN |
| to derive the full DN of each user logging in.</p><p>For example, if <span class="property">ldap-user-base-dn</span> is |
| "<code class="systemitem">ou=people,dc=example,dc=net</code>", as in the |
| example above, 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-config-base-dn</span></span></dt><dd><p>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, |
| where each member of a particular configuration group will have access |
| to that configuration.</p><p>This base DN will be used when querying the configurations accessible |
| by a user once they have successfully logged in.</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm139795231528960"></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="idm139795231520176" 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="idm139795231411184"></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="idm139795231409456"></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="noauth.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. Disabling authentication</td></tr></table></div> |
| |
| </div></div> |
| |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-75289145-1', 'auto'); |
| ga('send', 'pageview'); |
| |
| </script> |
| <!-- End Google Analytics --> |
| </body></html> |
