doc/1.4.0/gug/ldap-auth.html

<!DOCTYPE html> <html class="writer-html5" lang="en" > <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>LDAP authentication — Apache Guacamole Manual v1.4.0</title> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/tabs.css" type="text/css" /> <link rel="stylesheet" href="_static/gug.css" type="text/css" />  <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script src="_static/jquery.js"></script> <script src="_static/underscore.js"></script> <script src="_static/doctools.js"></script> <script src="_static/tabs.js"></script> <script type="text/javascript" src="_static/js/theme.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Duo two-factor authentication" href="duo-auth.html" /> <link rel="prev" title="Database authentication" href="jdbc-auth.html" /> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="index.html" class="icon icon-home"> Apache Guacamole </a> <div class="version"> 1.4.0 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> <p class="caption" role="heading"><span class="caption-text">Overview</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="introduction.html">Introduction</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">User's Guide</span></p> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="guacamole-architecture.html">Implementation and architecture</a></li> <li class="toctree-l1"><a class="reference internal" href="installing-guacamole.html">Installing Guacamole natively</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-docker.html">Installing Guacamole with Docker</a></li> <li class="toctree-l1"><a class="reference internal" href="reverse-proxy.html">Proxying Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="configuring-guacamole.html">Configuring Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="jdbc-auth.html">Database authentication</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">LDAP authentication</a><ul> <li class="toctree-l2"><a class="reference internal" href="#how-guacamole-uses-ldap">How Guacamole uses LDAP</a></li> <li class="toctree-l2"><a class="reference internal" href="#downloading-the-ldap-extension">Downloading the LDAP extension</a></li> <li class="toctree-l2"><a class="reference internal" href="#preparing-your-ldap-directory-optional">Preparing your LDAP directory (optional)</a><ul> <li class="toctree-l3"><a class="reference internal" href="#applying-the-schema-changes-to-openldap">Applying the schema changes to OpenLDAP</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#associating-ldap-with-a-database">Associating LDAP with a database</a></li> <li class="toctree-l2"><a class="reference internal" href="#installing-ldap-authentication">Installing LDAP authentication</a><ul> <li class="toctree-l3"><a class="reference internal" href="#configuring-guacamole-for-ldap">Configuring Guacamole for LDAP</a></li> <li class="toctree-l3"><a class="reference internal" href="#completing-the-installation">Completing the installation</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="#the-ldap-schema">The LDAP schema</a><ul> <li class="toctree-l3"><a class="reference internal" href="#users">Users</a></li> <li class="toctree-l3"><a class="reference internal" href="#connections-and-parameters">Connections and parameters</a></li> </ul> </li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="duo-auth.html">Duo two-factor authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="totp-auth.html">TOTP two-factor authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="header-auth.html">HTTP header authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="json-auth.html">Encrypted JSON authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="cas-auth.html">CAS Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="openid-auth.html">OpenID Connect Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="saml-auth.html">SAML Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="radius-auth.html">RADIUS Authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="adhoc-connections.html">Ad-hoc Connections</a></li> <li class="toctree-l1"><a class="reference internal" href="using-guacamole.html">Using Guacamole</a></li> <li class="toctree-l1"><a class="reference internal" href="administration.html">Administration</a></li> <li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Developer's Guide</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="guacamole-protocol.html">The Guacamole protocol</a></li> <li class="toctree-l1"><a class="reference internal" href="libguac.html">libguac</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-common.html">guacamole-common</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-common-js.html">guacamole-common-js</a></li> <li class="toctree-l1"><a class="reference internal" href="guacamole-ext.html">guacamole-ext</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-protocols.html">Adding new protocols</a></li> <li class="toctree-l1"><a class="reference internal" href="custom-auth.html">Custom authentication</a></li> <li class="toctree-l1"><a class="reference internal" href="event-listeners.html">Event listeners</a></li> <li class="toctree-l1"><a class="reference internal" href="writing-you-own-guacamole-app.html">Writing your own Guacamole application</a></li> </ul> <p class="caption" role="heading"><span class="caption-text">Appendices</span></p> <ul> <li class="toctree-l1"><a class="reference internal" href="protocol-reference.html">Guacamole protocol reference</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" aria-label="top navigation"> <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="index.html">Apache Guacamole</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="index.html" class="icon icon-home"></a> »</li> <li>LDAP authentication</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/ldap-auth.md.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <div class="section" id="ldap-authentication"> <h1>LDAP authentication<a class="headerlink" href="#ldap-authentication" title="Permalink to this headline">¶</a></h1> <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> <ol class="simple"> <li><p>An LDAP directory as storage for all authentication data, such as OpenLDAP.</p></li> <li><p>The ability to modify the schema of your LDAP directory.</p></li> </ol> <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="admonition important"> <p class="admonition-title">Important</p> <p>This chapter involves modifying the contents of <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME</span></code> - the Guacamole configuration directory. If you are unsure where <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME</span></code> is located on your system, please consult <a class="reference internal" href="configuring-guacamole.html"><span class="doc std std-doc">Configuring Guacamole</span></a> before proceeding.</p> </div> <div class="section" id="how-guacamole-uses-ldap"> <span id="ldap-architecture"></span><h2>How Guacamole uses LDAP<a class="headerlink" href="#how-guacamole-uses-ldap" title="Permalink to this headline">¶</a></h2> <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="docutils literal notranslate"><span class="pre">guacConfigGroup</span></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> <ol class="simple"> <li><p>Your users can use their existing usernames and passwords to log into Guacamole.</p></li> <li><p>You can manage Guacamole connections using the same tool that you already use to manage your LDAP directory, such as <a class="reference external" href="https://directory.apache.org/studio/">Apache Directory Studio</a>.</p></li> <li><p>Existing security restrictions can limit visibility/accessibility of Guacamole connections.</p></li> <li><p>Access to connections can easily be granted and revoked, as each connection is represented by a group.</p></li> </ol> <div class="admonition important"> <p class="admonition-title">Important</p> <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="reference internal" href="jdbc-auth.html"><span class="doc std std-doc">Database authentication</span></a> and later in this chapter in <a class="reference internal" href="#ldap-and-database"><span class="std std-ref">Associating LDAP with a database</span></a>.</p> </div> </div> <div class="section" id="downloading-the-ldap-extension"> <span id="ldap-downloading"></span><h2>Downloading the LDAP extension<a class="headerlink" href="#downloading-the-ldap-extension" title="Permalink to this headline">¶</a></h2> <p>The LDAP authentication extension is available separately from the main <code class="docutils literal notranslate"><span class="pre">guacamole.war</span></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="reference external" href="http://guacamole.apache.org/releases/">http://guacamole.apache.org/releases/</a>.</p> <p>The LDAP authentication extension is packaged as a <code class="docutils literal notranslate"><span class="pre">.tar.gz</span></code> file containing:</p> <dl class="simple myst"> <dt><code class="docutils literal notranslate"><span class="pre">guacamole-auth-ldap-1.4.0.jar</span></code></dt><dd><p>The Guacamole LDAP support extension itself, which must be placed in <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code>.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">schema/</span></code></dt><dd><p>LDAP schema files. An <code class="docutils literal notranslate"><span class="pre">.ldif</span></code> file compatible with OpenLDAP is provided, as well as a <code class="docutils literal notranslate"><span class="pre">.schema</span></code> file compliant with RFC-2252. The <code class="docutils literal notranslate"><span class="pre">.schema</span></code> file can be transformed into the <code class="docutils literal notranslate"><span class="pre">.ldif</span></code> file automatically.</p> </dd> </dl> </div> <div class="section" id="preparing-your-ldap-directory-optional"> <span id="ldap-schema-changes"></span><h2>Preparing your LDAP directory (optional)<a class="headerlink" href="#preparing-your-ldap-directory-optional" title="Permalink to this headline">¶</a></h2> <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="reference internal" href="#ldap-and-database"><span class="std std-ref">Associating LDAP with a database</span></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="docutils literal notranslate"><span class="pre">guacConfigGroup</span></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="docutils literal notranslate"><span class="pre">guacConfigGroup</span></code> will be accessible only by users who are members of that group (specified with the member attribute), or who are members of associated groups (specified with the <code class="docutils literal notranslate"><span class="pre">seeAlso</span></code> attribute).</p> <div class="admonition important"> <p class="admonition-title">Important</p> <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="docutils literal notranslate"><span class="pre">schema/</span></code> directory of the archive containing the LDAP extension. You will only need one of these files:</p> <dl class="simple myst"> <dt><code class="docutils literal notranslate"><span class="pre">guacConfigGroup.schema</span></code></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><code class="docutils literal notranslate"><span class="pre">guacConfigGroup.ldif</span></code></dt><dd><p>An LDIF file compatible with OpenLDAP. This file was automatically built from the provided <code class="docutils literal notranslate"><span class="pre">.schema</span></code> file for convenience.</p> </dd> </dl> <p>This chapter will cover applying <code class="docutils literal notranslate"><span class="pre">guacConfigGroup.ldif</span></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" id="applying-the-schema-changes-to-openldap"> <h3>Applying the schema changes to OpenLDAP<a class="headerlink" href="#applying-the-schema-changes-to-openldap" title="Permalink to this headline">¶</a></h3> <p>Schema changes to OpenLDAP are applied using the <strong class="command">ldapadd</strong> utility with the provided <code class="docutils literal notranslate"><span class="pre">guacConfigGroup.ldif</span></code> file:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">#</span> ldapadd -Q -Y EXTERNAL -H ldapi:/// -f schema/guacConfigGroup.ldif <span class="go">adding new entry "cn=guacConfigGroup,cn=schema,cn=config"</span> <span class="gp">#</span> </pre></div> </div> <p>If the <code class="docutils literal notranslate"><span class="pre">guacConfigGroup</span></code> object was added successfully, you should see output as above. You can confirm the presence of the new object class using <strong class="command">ldapsearch</strong>:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">#</span> ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b <span class="nv">cn</span><span class="o">=</span>schema,cn<span class="o">=</span>config dn <span class="go">dn: cn=schema,cn=config</span> <span class="go">dn: cn={0}core,cn=schema,cn=config</span> <span class="go">dn: cn={1}cosine,cn=schema,cn=config</span> <span class="go">dn: cn={2}nis,cn=schema,cn=config</span> <span class="go">dn: cn={3}inetorgperson,cn=schema,cn=config</span> <span class="go">dn: cn={4}guacConfigGroup,cn=schema,cn=config</span> <span class="gp">#</span> </pre></div> </div> </div> </div> <div class="section" id="associating-ldap-with-a-database"> <span id="ldap-and-database"></span><h2>Associating LDAP with a database<a class="headerlink" href="#associating-ldap-with-a-database" title="Permalink to this headline">¶</a></h2> <p>If you install both the LDAP authentication as well as support for a database (following the instructions in <a class="reference internal" href="jdbc-auth.html"><span class="doc std std-doc">Database authentication</span></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="reference internal" href="#guac-ldap-config"><span class="std std-ref">the <code class="docutils literal notranslate"><span class="pre">ldap-username-attribute</span></code> and <code class="docutils literal notranslate"><span class="pre">ldap-group-name-attribute</span></code> properties</span></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="docutils literal notranslate"><span class="pre">guacadmin</span></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" id="installing-ldap-authentication"> <span id="installing-ldap-auth"></span><h2>Installing LDAP authentication<a class="headerlink" href="#installing-ldap-authentication" title="Permalink to this headline">¶</a></h2> <p>Guacamole extensions are self-contained <code class="docutils literal notranslate"><span class="pre">.jar</span></code> files which are located within the <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code> directory. To install the LDAP authentication extension, you must:</p> <ol class="simple"> <li><p>Create the <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code> directory, if it does not already exist.</p></li> <li><p>Copy <code class="docutils literal notranslate"><span class="pre">guacamole-auth-ldap-1.4.0.jar</span></code> within <code class="docutils literal notranslate"><span class="pre">GUACAMOLE_HOME/extensions</span></code>.</p></li> <li><p>Configure Guacamole to use LDAP authentication, as described below.</p></li> </ol> <div class="admonition important"> <p class="admonition-title">Important</p> <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" id="configuring-guacamole-for-ldap"> <span id="guac-ldap-config"></span><h3>Configuring Guacamole for LDAP<a class="headerlink" href="#configuring-guacamole-for-ldap" title="Permalink to this headline">¶</a></h3> <p>Additional properties may be added to <code class="docutils literal notranslate"><span class="pre">guacamole.properties</span></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 ldap-user-base-dn property is required:</p> <dl class="simple myst"> <dt><code class="docutils literal notranslate"><span class="pre">ldap-hostname</span></code></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><code class="docutils literal notranslate"><span class="pre">ldap-port</span></code></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 <code class="docutils literal notranslate"><span class="pre">ldap-encryption-method</span></code> (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><code class="docutils literal notranslate"><span class="pre">ldap-encryption-method</span></code></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="docutils literal notranslate"><span class="pre">cacerts</span></code>. If this is not the case, you will need to use Java’s <code class="docutils literal notranslate"><span class="pre">keytool</span></code> 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="docutils literal notranslate"><span class="pre">cacerts</span></code>, you will need to specify the full path to that trust store using the system property <code class="docutils literal notranslate"><span class="pre">javax.net.ssl.trustStore</span></code>. Note that this is a system property and <em>not</em> a Guacamole property; it must be specified when starting the JVM using the <code class="docutils literal notranslate"><span class="pre">-D</span></code> option. Your servlet container will provide some means of specifying startup options for the JVM.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-max-search-results</span></code></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. <em>This property is optional.</em> If omitted, each LDAP query will be limited to a maximum of 1000 results.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-search-bind-dn</span></code></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 <code class="docutils literal notranslate"><span class="pre">ldap-user-base-dn</span></code>.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-search-bind-password</span></code></dt><dd><p>The password to provide to the LDAP server when binding as <code class="docutils literal notranslate"><span class="pre">ldap-search-bind-dn</span></code> to authenticate other users. This property is only used if ldap-search-bind-dn is specified. If omitted, but <code class="docutils literal notranslate"><span class="pre">ldap-search-bind-dn</span></code> is specified, Guacamole will attempt to bind with the LDAP server without a password.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-user-base-dn</span></code></dt><dd><p>The base of the DN for all Guacamole users. <em>This property is absolutely required in all cases.</em> All Guacamole users must be descendents of this base DN.</p> <p>If a search DN is provided (via <code class="docutils literal notranslate"><span class="pre">ldap-search-bind-dn</span></code>), then Guacamole users need only be somewhere within the subtree of the specified user base DN.</p> <p>If a search DN <em>is not</em> provided, then all Guacamole users must be <em>direct descendents</em> of this base DN, as the base DN will be appended to the username to derive the user’s DN. For example, if <code class="docutils literal notranslate"><span class="pre">ldap-user-base-dn</span></code> is “<code class="docutils literal notranslate"><span class="pre">ou=people,dc=example,dc=net</span></code>”, and <code class="docutils literal notranslate"><span class="pre">ldap-username-attribute</span></code> is “uid”, then a person attempting to login as “<code class="docutils literal notranslate"><span class="pre">user</span></code>” would be mapped to the following full DN: “<code class="docutils literal notranslate"><span class="pre">uid=user,ou=people,dc=example,dc=net</span></code>”.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-username-attribute</span></code></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 “uid”. If your LDAP directory contains users whose usernames are dictated by different attributes, multiple attributes can be specified here, separated by commas, but beware: <em>doing so requires that a search DN be provided with <code class="docutils literal notranslate"><span class="pre">ldap-search-bind-dn</span></code></em>.</p> <p>If a search DN <em>is not</em> 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 <code class="docutils literal notranslate"><span class="pre">ldap-user-base-dn</span></code> is “<code class="docutils literal notranslate"><span class="pre">ou=people,dc=example,dc=net</span></code>”, and <code class="docutils literal notranslate"><span class="pre">ldap-username-attribute</span></code> is “uid”, then a person attempting to login as “<code class="docutils literal notranslate"><span class="pre">user</span></code>” would be mapped to the following full DN: “<code class="docutils literal notranslate"><span class="pre">uid=user,ou=people,dc=example,dc=net</span></code>”.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-member-attribute</span></code></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 “member”. If your LDAP directory contains groups whose members are dictated by a different attribute, it can be specified here.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-member-attribute-type</span></code></dt><dd><p>Specify whether the attribute defined in <code class="docutils literal notranslate"><span class="pre">ldap-member-attribute</span></code> (Usually “member”) identifies a group member by DN or by usercode. Possible values: “dn” (the default, if not specified) or “uid”.</p> <p>Example: an LDAP server may present groups using the <code class="docutils literal notranslate"><span class="pre">groupOfNames</span></code> scheme:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>dn: cn=group1,ou=Groups,dc=example,dc=net objectClass: groupOfNames cn: group1 gidNumber: 12345 member: user1,ou=People,dc=example,dc=net member: user2,ou=People,dc=example,dc=net </pre></div> </div> <p><code class="docutils literal notranslate"><span class="pre">ldap-member-attribute</span></code> is <code class="docutils literal notranslate"><span class="pre">member</span></code> and <code class="docutils literal notranslate"><span class="pre">ldap-member-attribute-type</span></code> is <code class="docutils literal notranslate"><span class="pre">dn</span></code>.</p> <p>Example: an LDAP server may present groups using the <code class="docutils literal notranslate"><span class="pre">posixGroup</span></code> scheme:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>dn: cn=group1,ou=Groups,dc=example,dc=net objectClass: posixGroup cn: group1 gidNumber: 12345 memberUid: user1 memberUid: user2 </pre></div> </div> <p><code class="docutils literal notranslate"><span class="pre">ldap-member-attribute</span></code> is <code class="docutils literal notranslate"><span class="pre">memberUid</span></code> and <code class="docutils literal notranslate"><span class="pre">ldap-member-attribute-type</span></code> is <code class="docutils literal notranslate"><span class="pre">uid</span></code></p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-user-attributes</span></code></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="reference internal" href="configuring-guacamole.html#parameter-tokens"><span class="std std-ref">parameter tokens</span></a> with the prefix “<code class="docutils literal notranslate"><span class="pre">LDAP_</span></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="reference external" href="https://en.wikipedia.org/wiki/Naming_convention_(programming)#Multiple-word_identifiers">screaming snake case</a>”.</p> <p>For example:</p> <table class="colwidths-auto docutils align-default"> <thead> <tr class="row-odd"><th class="head"><p>LDAP Attribute</p></th> <th class="head"><p>Parameter Token</p></th> </tr> </thead> <tbody> <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">lowercase-with-dashes</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">${LDAP_LOWERCASE_WITH_DASHES}</span></code></p></td> </tr> <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">CamelCase</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">${LDAP_CAMEL_CASE}</span></code></p></td> </tr> <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">headlessCamelCase</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">${LDAP_HEADLESS_CAMEL_CASE}</span></code></p></td> </tr> <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">lettersAndNumbers1234</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">${LDAP_LETTERS_AND_NUMBERS_1234}</span></code></p></td> </tr> <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">aRANDOM_mixOf-3NAMINGConventions</span></code></p></td> <td><p><code class="docutils literal notranslate"><span class="pre">${LDAP_A_RANDOM_MIX_OF_3_NAMING_CONVENTIONS}</span></code></p></td> </tr> </tbody> </table> <p>Usage of parameter tokens is discussed in more detail in <a class="reference internal" href="configuring-guacamole.html"><span class="doc std std-doc">Configuring Guacamole</span></a> in <a class="reference internal" href="configuring-guacamole.html#parameter-tokens"><span class="std std-ref">Parameter tokens</span></a>.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-user-search-filter</span></code></dt><dd><p>The search filter used to query the LDAP tree for users that can log into and be granted privileges in Guacamole. <em>If this property is omitted the default of <code class="docutils literal notranslate"><span class="pre">(objectClass=*)</span></code> will be used.</em></p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-config-base-dn</span></code></dt><dd><p>The base of the DN for all Guacamole configurations. <em>This property is optional.</em> 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 <code class="docutils literal notranslate"><span class="pre">member</span></code> attribute) and optionally group members (via the <code class="docutils literal notranslate"><span class="pre">seeAlso</span></code> attribute), where each member of a particular configuration group will have access to the connection defined by that configuration.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-group-base-dn</span></code></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 seeAlso attribute. All groups which will be used to control access to Guacamole configurations must be descendents of this base DN. <em>If this property is omitted, the <code class="docutils literal notranslate"><span class="pre">seeAlso</span></code> attribute will have no effect on Guacamole configurations.</em></p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-group-name-attribute</span></code></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 “cn”. 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><code class="docutils literal notranslate"><span class="pre">ldap-group-search-filter</span></code></dt><dd><p>The search filter used to query the LDAP tree for groups that may be used by other extensions to define permissions. <em>If this property is omitted the default of <code class="docutils literal notranslate"><span class="pre">(objectClass=*)</span></code> will be used.</em></p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-dereference-aliases</span></code></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><code class="docutils literal notranslate"><span class="pre">ldap-follow-referrals</span></code></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 encountered 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><code class="docutils literal notranslate"><span class="pre">ldap-max-referral-hops</span></code></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 <code class="docutils literal notranslate"><span class="pre">ldap-follow-referrals</span></code> property is set to false (the default), this option has no effect. If the <code class="docutils literal notranslate"><span class="pre">ldap-follow-referrals</span></code> option is set to true, this will limit the depth of referrals followed to the number specified.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">ldap-operation-timeout</span></code></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> <p>Again, even if the defaults are sufficient for the other properties, <em>you must still specify the <code class="docutils literal notranslate"><span class="pre">ldap-user-base-dn</span></code> property</em>. An absolutely minimal configuration for LDAP authentication will look like the following:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span># LDAP properties ldap-user-base-dn: ou=people,dc=example,dc=net </pre></div> </div> </div> <div class="section" id="completing-the-installation"> <h3>Completing the installation<a class="headerlink" href="#completing-the-installation" title="Permalink to this headline">¶</a></h3> <p>Guacamole will only reread <code class="docutils literal notranslate"><span class="pre">guacamole.properties</span></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> <div class="admonition important"> <p class="admonition-title">Important</p> <p>You only need to restart your servlet container. <em>You do not need to restart guacd</em>.</p> <p>guacd is completely independent of the web application and does not deal with <code class="docutils literal notranslate"><span class="pre">guacamole.properties</span></code> or the authentication system in any way. Since you are already restarting the servlet container, restarting guacd as well technically won’t hurt anything, but doing so is completely pointless.</p> </div> <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 ldap-user-base-dn.</p> </div> </div> <div class="section" id="the-ldap-schema"> <span id="ldap-auth-schema"></span><h2>The LDAP schema<a class="headerlink" href="#the-ldap-schema" title="Permalink to this headline">¶</a></h2> <p>Guacamole’s LDAP support allows users and connections to be managed purely within an LDAP directory defined in <code class="docutils literal notranslate"><span class="pre">guacamole.properties</span></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="docutils literal notranslate"><span class="pre">guacConfigGroup</span></code>, which was added to your server’s schema during the install process above.</p> <div class="section" id="users"> <h3>Users<a class="headerlink" href="#users" title="Permalink to this headline">¶</a></h3> <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" id="connections-and-parameters"> <h3>Connections and parameters<a class="headerlink" href="#connections-and-parameters" title="Permalink to this headline">¶</a></h3> <p>Each connection is represented by an instance of the <code class="docutils literal notranslate"><span class="pre">guacConfigGroup</span></code> object class, an extended version of the standard LDAP <code class="docutils literal notranslate"><span class="pre">groupOfNames</span></code>, which provides a protocol and set of parameters. Only members of the <code class="docutils literal notranslate"><span class="pre">guacConfigGroup</span></code> will have access to the corresponding connection.</p> <p>The <code class="docutils literal notranslate"><span class="pre">guacConfigGroup</span></code> object class provides two new attributes in addition to those provided by <code class="docutils literal notranslate"><span class="pre">groupOfNames</span></code>:</p> <dl class="simple myst"> <dt><code class="docutils literal notranslate"><span class="pre">guacConfigProtocol</span></code></dt><dd><p>The protocol associated with the connection, such as “<code class="docutils literal notranslate"><span class="pre">vnc</span></code>” or “<code class="docutils literal notranslate"><span class="pre">rdp</span></code>”. This attribute is required for every <code class="docutils literal notranslate"><span class="pre">guacConfigGroup</span></code> and can be given only once.</p> </dd> <dt><code class="docutils literal notranslate"><span class="pre">guacConfigParameter</span></code></dt><dd><p>The name and value of a parameter for the specified protocol. This is given as <code class="docutils literal notranslate"><span class="pre">name=value</span></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> <p>For example, to create a new VNC connection which connects to “localhost” at port 5900, while granting access to <code class="docutils literal notranslate"><span class="pre">user1</span></code> and <code class="docutils literal notranslate"><span class="pre">user2</span></code>, you could create an <code class="docutils literal notranslate"><span class="pre">.ldif</span></code> file like the following:</p> <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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> </div> <p>The new connection can then be created using the <strong class="command">ldapadd</strong> utility:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> ldapadd -x -D <span class="nv">cn</span><span class="o">=</span>admin,dc<span class="o">=</span>example,dc<span class="o">=</span>net -W -f example-connection.ldif <span class="go">Enter LDAP Password:</span> <span class="go">adding new entry "cn=Example Connection,ou=groups,dc=example,dc=net"</span> <span class="gp">$</span> </pre></div> </div> <p>Where <code class="docutils literal notranslate"><span class="pre">cn=admin,dc=example,dc=net</span></code> is an administrator account with permission to create new entries, and <code class="docutils literal notranslate"><span class="pre">example-connection.ldif</span></code> is the name of the <code class="docutils literal notranslate"><span class="pre">.ldif</span></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="reference external" href="https://directory.apache.org/studio/">Apache Directory Studio</a>, which make many of the tasks given above much easier.</p> </div> </div> </div> </div> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> <a href="duo-auth.html" class="btn btn-neutral float-right" title="Duo two-factor authentication" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a> <a href="jdbc-auth.html" class="btn btn-neutral float-left" title="Database authentication" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a> </div> <hr/> <div role="contentinfo"> <p>Copyright © 2021 <a href="http://www.apache.org/">The Apache Software Foundation</a>, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>. Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation.</p> </div> Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. </footer> </div> </div> </section> </div> <script type="text/javascript"> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>

doc/1.4.0/gug/ldap-auth.html (645 lines of code) (raw):