Merge pull request #26 from glyptodon/improved-auth
GUAC-1331: Document support for multiple auth extensions
diff --git a/src/chapters/configuring.xml b/src/chapters/configuring.xml
index 6099dfe..bbbb0ce 100644
--- a/src/chapters/configuring.xml
+++ b/src/chapters/configuring.xml
@@ -263,8 +263,9 @@
</indexterm>
<para>Guacamole's default authentication module is simple and consists of a mapping of
usernames to configurations. This authentication module comes with Guacamole and simply
- reads usernames and passwords from an XML file. If you wish to use this authentication
- mechanism, simply do not install and authentication extensions.</para>
+ reads usernames and passwords from an XML file. It is always enabled, but will only read
+ from the XML file if it exists, and is always last in priority relative to any other
+ authentication extensions.</para>
<para>There are other authentication modules available. The Guacamole project provides
database-backed authentication modules with the ability to manage connections and users
from the web interface, and other authentication modules can be created using the
@@ -280,7 +281,7 @@
default, Guacamole will look for this file at
<filename>GUACAMOLE_HOME/user-mapping.xml</filename>, but this can be overridden
by specifying the location with the <property>user-mapping</property> property
- within guacamole.properties:</para>
+ within <filename>guacamole.properties</filename>:</para>
<informalexample>
<programlisting>user-mapping: <replaceable>/path/to/user-mapping.xml</replaceable></programlisting>
</informalexample>
diff --git a/src/chapters/guacamole-ext.xml b/src/chapters/guacamole-ext.xml
index 9fc6c40..b05ce72 100644
--- a/src/chapters/guacamole-ext.xml
+++ b/src/chapters/guacamole-ext.xml
@@ -99,10 +99,7 @@
<entry>
<para>An array of the classnames of all
<classname>AuthenticationProvider</classname> subclasses
- provided by this extension. Guacamole currently only supports
- one <classname>AuthenticationProvider</classname> being loaded
- at a time, thus this array must only contain one element, if it
- is present at all.</para>
+ provided by this extension.</para>
</entry>
</row>
<row>
diff --git a/src/chapters/jdbc-auth.xml b/src/chapters/jdbc-auth.xml
index c2a8c6c..0fc6a18 100644
--- a/src/chapters/jdbc-auth.xml
+++ b/src/chapters/jdbc-auth.xml
@@ -13,14 +13,19 @@
<primary>load balancing</primary>
</indexterm>
<para>Guacamole supports authentication via MySQL or PostgreSQL databases through extensions
- available from the project website. These extensions allow users and connections to be
- managed from within the web application. Unlike the default, XML-driven authentication
- module, all changes to users and connections take effect immediately; users need not logout
- and back in to see new connections.</para>
- <para>The official database authentication also supports load balancing through the use of
- "balancing groups". When a balancing group is created, it can be used like any other
- connection, but will use the least-used of its underlying connections, spreading load evenly
- across any connections contained within.</para>
+ available from the project website. Using a database for authentication provides additional
+ features, such as the ability to use load balancing groups of connections and a web-based
+ administrative interface. Unlike the default, XML-driven authentication module, all changes
+ to users and connections take effect immediately; users need not logout and back in to see
+ new connections.</para>
+ <para>While most authentication extensions function independently, the database authentication
+ can act in a subordinate role, allowing users from other authentication extensions to be
+ associated with connections within the database. Users are considered identical to users
+ within the database if they have the same usernames, and the authentication result of
+ another extension will be trusted if it succeeds. A user with an account under multiple
+ systems will thus be able to see data from each system after successfully logging in. For
+ more information on using the database authentication alongside other mechanisms, see <xref
+ linkend="ldap-and-database"/> within <xref linkend="ldap-auth"/>.</para>
<para>To use the database authentication extension, you will need:</para>
<orderedlist>
<listitem>
@@ -97,8 +102,8 @@
</section>
<section xml:id="jdbc-auth-database-creation">
<title>Creating the Guacamole database</title>
- <para>The database authentication module will need a database to store all authentication
- data and a user to use only for data access and manipulation. You can use an existing
+ <para>The database authentication module will need a database to store authentication data
+ and a user to use only for data access and manipulation. You can use an existing
database and existing user, but for the sake of simplicity and security, these
instructions assume you will be creating a new database and new user that will be used
only by Guacamole and only for this authentication module.</para>
diff --git a/src/chapters/ldap-auth.xml b/src/chapters/ldap-auth.xml
index 0bccfcc..1284973 100644
--- a/src/chapters/ldap-auth.xml
+++ b/src/chapters/ldap-auth.xml
@@ -29,7 +29,7 @@
<varname>GUACAMOLE_HOME</varname> is located on your system, please consult <xref
linkend="configuring-guacamole"/> before proceeding.</para>
</important>
- <section>
+ <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
@@ -61,15 +61,23 @@
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>
+ <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://guac-dev.org/releases/"
- >http://guac-dev.org/releases/</link>.</para>
+ >http://guac-dev.org/releases/</link>.</para>
<para>The LDAP authentication extension is packaged as a <filename>.tar.gz</filename> file
containing:</para>
<variablelist>
@@ -91,20 +99,22 @@
</varlistentry>
</variablelist>
</section>
- <section>
- <title>Preparing your LDAP directory</title>
+ <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.</para>
- <para>This need for additional connection storage means that the LDAP directory schema must
- be modified. An additional object, <classname>guacConfigGroup</classname>, 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.</para>
- <para>The necessary modifications to the LDAP schema are made through applying one of the
- provided schema files. <emphasis>This must be done before Guacamole can be used with
- LDAP</emphasis>.</para>
+ 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. Only
+ users which are members of a connection's group will have access to that
+ connection.</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
@@ -167,6 +177,26 @@
</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 MySQL or PostgreSQL
+ (following the instructions in <xref linkend="jdbc-auth"/>), 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.</para>
+ <para>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.</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 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.</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
