GUACAMOLE-88: Expand documentation covering authentication process.

Project: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/repo
Commit: 
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/commit/19620381
Tree: 
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/19620381
Diff: 
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/19620381

Branch: refs/heads/master
Commit: 19620381e259fe4018fbff0a1ebb823e5d72b337
Parents: 93fff04
Author: Michael Jumper <mjum...@apache.org>
Authored: Sun Oct 16 13:47:52 2016 -0700
Committer: Michael Jumper <mjum...@apache.org>
Committed: Sun Oct 16 13:47:52 2016 -0700

----------------------------------------------------------------------
 src/chapters/guacamole-ext.xml | 557 +++++++++++++++++++-----------------
 1 file changed, 294 insertions(+), 263 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/19620381/src/chapters/guacamole-ext.xml
----------------------------------------------------------------------
diff --git a/src/chapters/guacamole-ext.xml b/src/chapters/guacamole-ext.xml
index 25216da..98983a6 100644
--- a/src/chapters/guacamole-ext.xml
+++ b/src/chapters/guacamole-ext.xml
@@ -32,7 +32,7 @@
                 languages.</para>
         </listitem>
     </orderedlist>
-    <section xml:id="extension-format">
+    <section xml:id="ext-file-format">
         <title>Guacamole extension format</title>
         <para>Guacamole extensions are standard Java <filename>.jar</filename> 
files which contain
             all classes and resources required by the extension, as well as 
the Guacamole extension
@@ -41,7 +41,7 @@
                 <filename>.jar</filename> relative to the root, as well.</para>
         <para>Beyond this, the semantics and locations associated with all 
other resources within
             the extension are determined by the extension manifest 
alone.</para>
-        <section xml:id="extension-manifest">
+        <section xml:id="ext-manifest">
             <title>Extension manifest</title>
             <para>The Guacamole extension manifest is a single JSON file,
                     <filename>guac-manifest.json</filename>, which describes 
the location of each
@@ -204,7 +204,7 @@
 }</programlisting>
             </informalexample>
         </section>
-        <section xml:id="patch-html">
+        <section xml:id="ext-patch-html">
             <title>Updating existing HTML</title>
             <para>The existing HTML structure of Guacamole's interface can be 
modified by extensions
                 through special "patch" HTML files declared by the 
<property>html</property>
@@ -298,7 +298,7 @@
                 part of Guacamole's HTML in the first place.</para>
         </section>
     </section>
-    <section xml:id="environment">
+    <section xml:id="ext-environment">
         <title>Accessing the server configuration</title>
         <para>The configuration of the Guacamole server is exposed through the
                 <classname>Environment</classname> interface, specifically the
@@ -307,7 +307,7 @@
                 <filename>guacamole.properties</filename>, determine the 
proper hostname/port of
                 <package>guacd</package>, and access the contents of
                 <varname>GUACAMOLE_HOME</varname>.</para>
-        <section xml:id="simple-config">
+        <section xml:id="ext-simple-config">
             <title>Custom properties</title>
             <para>If your extension requires generic, unstructured 
configuration parameters,
                     <filename>guacamole.properties</filename> is a reasonable 
and simple location
@@ -398,7 +398,7 @@
                 the name of the property, and 
<methodname>parseValue()</methodname>, which parses a
                 given string and returns its value.</para>
         </section>
-        <section xml:id="advanced-config">
+        <section xml:id="ext-advanced-config">
             <title>Advanced configuration</title>
             <para>If you need more structured data than provided by simple 
properties, you can place
                 completely arbitrary files in a hierarchy of your choosing 
anywhere within
@@ -418,272 +418,303 @@
             </informalexample>
         </section>
     </section>
-    <section xml:id="auth-providers">
+    <section xml:id="ext-auth-providers">
         <title>Authentication providers</title>
-        <para>The main use of guacamole-ext is to provide custom authentication
-            for Guacamole through the implementation of authentication
-            providers. An authentication provider is any class which implements
-            the <classname>AuthenticationProvider</classname> interface,
-            implementing the only function defined by that interface:
-                <methodname>getUserContext()</methodname>. This function is
-            required to return a "context" which provides access to only those
-            users and configurations accessible with the given credentials, and
-            enforces its own security model.</para>
-        <para>The credentials given are abstract and while Guacamole the web
-            application implements a username/password driven login screen, you
-            are not required to user usernames and passwords; the
-                <classname>Credentials</classname> class given to the
-            authentication provider provides access to all HTTP parameters in
-            general, as well as cookies and SSL information.</para>
-        <para>The Guacamole web application includes a basic authentication
-            provider implementation which parses an XML file to determine which
-            users exist, their corresponding passwords, and what configurations
-            those users have access to. This is the part of Guacamole that 
reads
-            the <filename>user-mapping.xml</filename> file. If you use a custom
-            authentication provider for your authentication, this file will
-            probably not be required.</para>
-        <para>The community has implemented authentication providers which
-            access databases, use LDAP, or even perform no authentication at
-            all, redirecting all users to a single configuration specified in
-                <filename>guacamole.properties</filename>.</para>
-        <para>A minimal authentication provider is implemented in the tutorials
-            later, and the upstream authentication provider implemented within
-            Guacamole, as well as the authentication providers implemented by
-            the community, are good examples for how authentication can be
-            extended without having to implement a whole new web
+        <para>Guacamole's authentication system is driven by authentication 
providers, which are
+            classes which implement the 
<classname>AuthenticationProvider</classname> interface
+            defined by guacamole-ext. When any page within Guacamole is 
visited, the following
+            process occurs:</para>
+        <orderedlist>
+            <listitem>
+                <para>All currently installed extensions are polled, in 
lexicographic order of their
+                    filenames, by invoking the 
<methodname>getAuthenticatedUser()</methodname>
+                    function with a <classname>Credentials</classname> object 
constructed with the
+                    contents of the HTTP request.</para>
+                <para>The credentials given are abstract. While the 
Credentials object provides
+                    convenience access to a traditional username and password,
+                        <emphasis>implementations are not required to use 
usernames and
+                        passwords</emphasis>. The entire contents of the HTTP 
request is at your
+                    disposal, including parameters, cookies, and SSL 
information.</para>
+            </listitem>
+            <listitem>
+                <para>If an authentication attempt fails, the extension throws 
either a
+                        
<classname>GuacamoleInsufficientCredentialsException</classname> (if more
+                    credentials are needed before validity can be determined) 
or
+                        
<classname>GuacamoleInvalidCredentialsException</classname> (if the
+                    credentials are technically sufficient, but are invalid as 
provided). If all
+                    extensions fail to authenticate the user, the contents of 
the exception thrown
+                    by the first extension to fail are used to produce the 
user login prompt.</para>
+                <para><emphasis>Note that this means there is no "login 
screen" in Guacamole per se;
+                        the prompt for credentials for unauthenticated users 
is determined purely
+                        based on the needs of the extension as declared within 
the authentication
+                        failure itself.</emphasis></para>
+                <para>If an authentication attempt succeeds, the extension 
returns an instance of
+                        <classname>AuthenticatedUser</classname> describing 
the identity of the user
+                    that just authenticated, and no further extensions are 
polled.</para>
+            </listitem>
+            <listitem>
+                <para>If authentication has succeeded, and thus an
+                        <classname>AuthenticatedUser</classname> is available, 
that
+                        <classname>AuthenticatedUser</classname> is passed to 
the
+                        <methodname>getUserContext()</methodname> function of 
all extensions'
+                    authentication providers. Each extension now has the 
opportunity to provide
+                    access to data for a user, even if that extension did not 
originally
+                    authenticate the user. If no 
<classname>UserContext</classname> is returned for
+                    the given <classname>AuthenticatedUser</classname>, then 
that extension has
+                    simply refused to provide data for that user.</para>
+                <para>The Guacamole interface will transparently unify the 
data from each extension,
+                    providing the user with a view of all available 
connections. If the user has
+                    permission to modify or administer any objects associated 
with an extension,
+                    access to the administrative interface will be exposed as 
well, again with a
+                    unified view of all applicable objects.</para>
+            </listitem>
+        </orderedlist>
+        <important>
+            <para>Because authentication is decoupled from data 
storage/access, <emphasis>you do not
+                    need to implement full-blown data storage if you only wish 
to provide an
+                    additional authentication mechanism</emphasis>. You can 
instead implement only
+                the authentication portion of an 
<classname>AuthenticationProvider</classname>, and
+                otherwise rely on the storage and features provided by other 
extensions, such as the
+                    <link xmlns:xlink="http://www.w3.org/1999/xlink"; 
linkend="jdbc-auth">database
+                    authentication extension</link>.</para>
+        </important>
+        <para>The Guacamole web application includes a basic authentication 
provider implementation
+            which parses an XML file to determine which users exist, their 
corresponding passwords,
+            and what configurations those users have access to. This is the 
part of Guacamole that
+            reads the <filename>user-mapping.xml</filename> file. If you use a 
custom authentication
+            provider for your authentication, this file will probably not be 
required.</para>
+        <para>The community has implemented authentication providers which 
access databases, use
+            LDAP, or even perform no authentication at all, redirecting all 
users to a single
+            configuration specified in 
<filename>guacamole.properties</filename>.</para>
+        <para>A minimal authentication provider is implemented in the 
tutorials later, and the
+            upstream authentication provider implemented within Guacamole, as 
well as the
+            authentication providers implemented by the community, are good 
examples for how
+            authentication can be extended without having to implement a whole 
new web
             application.</para>
-        <section>
+        <section xml:id="ext-simple-auth">
             <title><classname>SimpleAuthenticationProvider</classname></title>
-            <para>The <classname>SimpleAuthenticationProvider</classname> class
-                provides a much simpler means of implementing authentication
-                when you do not require the ability to add and remove users and
-                connections. It is an abstract class and requires only one
+            <para>The <classname>SimpleAuthenticationProvider</classname> 
class provides a much
+                simpler means of implementing authentication when you do not 
require the ability to
+                add and remove users and connections. It is an abstract class 
and requires only one
                 function implementation:
-                    
<methodname>getAuthorizedConfigurations()</methodname>.</para>
-            <para>This function is required to return a
-                    <classname>Map</classname> of unique IDs to configurations,
-                where these configurations are all configurations accessible
-                with the provided credentials. As before, the credentials given
-                are abstract. You are not required to use usernames and
-                passwords.</para>
-            <para>The configurations referred to by the function name are
-                instances of <classname>GuacamoleConfiguration</classname> 
(part
-                of guacamole-common), which is just a wrapper around a protocol
-                name and set of parameter name/value pairs. The name of the
-                protocol to use and a set of parameters is the minimum
-                information required for other parts of the Guacamole API to
-                complete the handshake required by the Guacamole
-                protocol.</para>
-            <para>When a class that extends
-                    <classname>SimpleAuthenticationProvider</classname> is 
asked
-                for more advanced operations by the web application,
-                    <classname>SimpleAuthenticationProvider</classname> simply
-                returns that there is no permission to do so. This effectively
-                disables all administrative functionality within the web
-                interface.</para>
-            <para>If you choose to go the simple route, most of the rest of 
this
-                chapter is irrelevant. Permissions, security model, and various
-                classes will be discussed that are all handled for you
-                automatically by
+                <methodname>getAuthorizedConfigurations()</methodname>.</para>
+            <para>This function is required to return a 
<classname>Map</classname> of unique IDs to
+                configurations, where these configurations are all 
configurations accessible with
+                the provided credentials. As before, the credentials given are 
abstract. You are not
+                required to use usernames and passwords.</para>
+            <para>The configurations referred to by the function name are 
instances of
+                    <classname>GuacamoleConfiguration</classname> (part of 
guacamole-common), which
+                is just a wrapper around a protocol name and set of parameter 
name/value pairs. The
+                name of the protocol to use and a set of parameters is the 
minimum information
+                required for other parts of the Guacamole API to complete the 
handshake required by
+                the Guacamole protocol.</para>
+            <para>When a class that extends 
<classname>SimpleAuthenticationProvider</classname> is
+                asked for more advanced operations by the web application,
+                    <classname>SimpleAuthenticationProvider</classname> simply 
returns that there is
+                no permission to do so. This effectively disables all 
administrative functionality
+                within the web interface.</para>
+            <para>If you choose to go the simple route, most of the rest of 
this chapter is
+                irrelevant. Permissions, security model, and various classes 
will be discussed that
+                are all handled for you automatically by
                     <classname>SimpleAuthenticationProvider</classname>.</para>
         </section>
+    </section>
+    <section xml:id="ext-user-context">
+        <title>The <classname>UserContext</classname></title>
+        <para>The <classname>UserContext</classname> is the root of all 
data-related operations. It
+            is used to list, create, modify, or delete users and connections, 
as well as to query
+            available permissions. If an extension is going to provide access 
to data of any sort,
+            it must do so through the 
<classname>UserContext</classname>.</para>
+        <para>The Guacamole web application uses permissions queries against 
the
+                <classname>UserContext</classname> to determine what 
operations to present, but
+                <emphasis>beware that it is up to the 
<classname>UserContext</classname> to actually
+                enforce these restrictions</emphasis>. The Guacamole web 
application will not
+            enforce restrictions on behalf of the 
<classname>UserContext</classname>.</para>
+        <para>The <classname>UserContext</classname> is the sole means of 
entry and the sole means
+            of modification available to a logged-in user. If the 
<classname>UserContext</classname>
+            refuses to perform an operation (by throwing an exception), the 
user cannot perform the
+            operation at all.</para>
+    </section>
+    <section xml:id="ext-object-directories">
+        <title><classname>Directory</classname> classes</title>
+        <para>Access to objects beneath the <classname>UserContext</classname> 
is given through
+                <classname>Directory</classname> classes. These 
<classname>Directory</classname>
+            classes are similar to Java collections, but they also embody 
update and batching
+            semantics. Objects can be retrieved from a 
<classname>Directory</classname> using its
+                <methodname>get()</methodname> function and added or removed 
with
+                <methodname>add()</methodname> and 
<methodname>remove()</methodname> respectively,
+            but objects already in the set can also be updated by passing an 
updated object to its
+                <methodname>update()</methodname> function.</para>
+        <para>An implementation of a <classname>Directory</classname> can rely 
on these functions to
+            define the semantics surrounding all operations. The 
<methodname>add()</methodname>
+            function is called only when creating new objects, the 
<methodname>update()</methodname>
+            function is called only when updating an object previously 
retrieved with
+                <methodname>get()</methodname>, and 
<methodname>remove()</methodname> is called only
+            when removing an existing object by its identifier.</para>
+        <para>When implementing an 
<classname>AuthenticationProvider</classname>, you must ensure
+            that the <classname>UserContext</classname> will only return
+                <classname>Directory</classname> classes that automatically 
enforce the permissions
+            associated with all objects and the associated user.</para>
+    </section>
+    <section xml:id="ext-permissions">
+        <title>Permissions</title>
+        <para>The permissions system within guacamole-ext is an advisory 
system. It is the means by
+            which an authentication module describes to the web application 
what a user is allowed
+            to do. The body of permissions granted to a user describes which 
objects that user can
+            see and what they can do to those objects, and thus suggests how 
the Guacamole interface
+            should appear to that user.</para>
+        <para><emphasis>Permissions are not the means by which access is 
restricted</emphasis>; they
+            are purely a means of describing access level. An implementation 
may internally use the
+            permission objects to define restrictions, but this is not 
required. It is up to the
+            implementation to enforce its own restrictions by throwing 
exceptions when an operation
+            is not allowed, and to correctly communicate the abilities of 
individual users through
+            these permissions.</para>
+        <para>The permissions available to a user are exposed through the
+                <classname>SystemPermissionSet</classname> and
+                <classname>ObjectPermissionSet</classname> classes which are 
accessible through the
+                <classname>UserContext</classname>. These classes also serve 
as the means for
+            manipulating the permissions granted to a user.</para>
         <section>
-            <title>The <classname>UserContext</classname></title>
-            <para>The <classname>UserContext</classname> is the root of all
-                operations. It is used to list, create, modify, or delete users
-                and connections, as well as to query available
-                permissions.</para>
-            <para>The Guacamole web application uses permissions queries 
against
-                the <classname>UserContext</classname> to determine what
-                operations to present, but <emphasis>beware that it is up to 
the
-                        <classname>UserContext</classname> to actually enforce
-                    these restrictions</emphasis>. The Guacamole web 
application
-                will not enforce restrictions on behalf of the
-                    <classname>UserContext</classname>.</para>
-            <para>The <classname>UserContext</classname> is the sole means of
-                entry and the sole means of modification available to a
-                logged-in user. If the <classname>UserContext</classname>
-                refuses to perform an operation (by throwing an exception), the
-                user cannot perform the operation at all.</para>
-        </section>
-        <section>
-            <title><classname>Directory</classname> classes</title>
-            <para>Access to users and connections is given through
-                    <classname>Directory</classname> classes. These
-                    <classname>Directory</classname> classes are similar to 
Java
-                collections, but they also embody object update semantics.
-                Objects can be retrieved from a 
<classname>Directory</classname>
-                using its <methodname>get()</methodname> function and added or
-                removed with <methodname>add()</methodname> and
-                    <methodname>remove()</methodname> respectively, but objects
-                already in the set can also be updated by passing an updated
-                object to its <methodname>update()</methodname> 
function.</para>
-            <para>An implementation of a <classname>Directory</classname> can
-                rely on these functions to define the semantics surrounding all
-                operations. The <methodname>add()</methodname> function is
-                called only when creating new objects, the
-                    <methodname>update()</methodname> function is called only
-                when updating an object previously retrieved with
-                    <methodname>get()</methodname>, and
-                    <methodname>remove()</methodname> is called only when
-                removing an existing object by its identifier.</para>
-            <para>When implementing an
-                    <classname>AuthenticationProvider</classname>, you must
-                ensure that the <classname>UserContext</classname> will only
-                return <classname>Directory</classname> classes that
-                automatically enforce the permissions associated with all
-                objects and the associated user.</para>
-        </section>
-        <section>
-            <title>Permissions</title>
-            <para>The permissions system within guacamole-ext is an advisory 
system. It is the means
-                by which an authentication module describes to the web 
application what a user is
-                allowed to do. The body of permissions granted to a user 
describes which objects
-                that user can see and what they can do to those objects, and 
thus suggests how the
-                Guacamole interface should appear to that user.</para>
-            <para><emphasis>Permissions are not the means by which access is 
restricted</emphasis>;
-                they are purely a means of describing access level. An 
implementation may internally
-                use the permission objects to define restrictions, but this is 
not required. It is
-                up to the implementation to enforce its own restrictions by 
throwing exceptions when
-                an operation is not allowed, and to correctly communicate the 
abilities of
-                individual users through these permissions.</para>
-            <section>
-                <title>System permissions</title>
-                <para>System permissions describe access to operations that 
manipulate the system as
-                    a whole, rather than specific objects. This includes the 
creation of new
-                    objects, as object creation directly affects the system, 
and per-object controls
-                    cannot exist before the object is actually created.</para>
-                <variablelist>
-                    <varlistentry>
-                        <term><constant>ADMINISTER</constant></term>
-                        <listitem>
-                            <para>The user is a super-user - the Guacamole 
equivalent of root. They
-                                are allowed to manipulate of system-level 
permissions and all other
-                                objects. This permission implies all 
others.</para>
-                        </listitem>
-                    </varlistentry>
-                    <varlistentry>
-                        <term><constant>CREATE_CONNECTION</constant></term>
-                        <listitem>
-                            <para>The user is allowed to create new 
connections. If a user has this
-                                permission, the management interface will 
display components related
-                                to connection creation.</para>
-                        </listitem>
-                    </varlistentry>
-                    <varlistentry>
-                        
<term><constant>CREATE_CONNECTION_GROUP</constant></term>
-                        <listitem>
-                            <para>The user is allowed to create new connection 
groups. If a user has
-                                this permission, the management interface will 
display components
-                                related to connection group creation.</para>
-                        </listitem>
-                    </varlistentry>
-                    <varlistentry>
-                        
<term><constant>CREATE_SHARING_PROFILE</constant></term>
-                        <listitem>
-                            <para>The user is allowed to create new sharing 
profiles. If a user has
-                                this permission, the management interface will 
display components
-                                related to sharing profile creation.</para>
-                        </listitem>
-                    </varlistentry>
-                    <varlistentry>
-                        <term><constant>CREATE_USER</constant></term>
-                        <listitem>
-                            <para>The user is allowed to create other users. 
If a user has this
-                                permission, the management interface will 
display components related
-                                to user creation.</para>
-                        </listitem>
-                    </varlistentry>
-                </variablelist>
-            </section>
-            <section>
-                <title>Object permissions</title>
-                <para>Object permissions describe access to operations that 
affect a particular
-                    object. Guacamole currently defines four types of objects 
which can be
-                    associated with permissions: users, connections, 
connection groups, and sharing
-                    profiles. Each object permission associates a single user 
with an action that
-                    may be performed on a single object.</para>
-                <variablelist>
-                    <varlistentry>
-                        <term><constant>ADMINISTER</constant></term>
-                        <listitem>
-                            <para>The user may grant or revoke permissions 
involving this object.
-                                "Involving", in this case, refers to either 
side of the permission
-                                association, and includes both the user to 
whom the permission is
-                                granted and the object the permission 
affects.</para>
-                        </listitem>
-                    </varlistentry>
-                    <varlistentry>
-                        <term><constant>DELETE</constant></term>
-                        <listitem>
-                            <para>The user may delete this object. This is 
distinct from the
-                                    <constant>ADMINISTER</constant> permission 
which deals only with
-                                permissions. A user with this permission will 
see the "Delete"
-                                button when applicable.</para>
-                        </listitem>
-                    </varlistentry>
-                    <varlistentry>
-                        <term><constant>READ</constant></term>
-                        <listitem>
-                            <para>The user may see that this object exists and 
read the properties
-                                of that object.</para>
-                            <para>Note that the implementation is 
<emphasis>not required to divulge
-                                    the true underlying properties of any 
object</emphasis>. The
-                                parameters of a connection or sharing profile, 
the type or contents
-                                of a connection group, the password of a user, 
etc. all need not be
-                                exposed.</para>
-                            <para>This is particularly important from the 
perspective of security
-                                when it comes to connections, as the 
parameters of a connection are
-                                only truly needed when a connection is being 
modified, and likely
-                                should not be exposed otherwise. The actual 
connection operation is
-                                always performed internally by the 
authentication provider, and thus
-                                does not require client-side knowledge of 
anything beyond the
-                                connection's existence.</para>
-                        </listitem>
-                    </varlistentry>
-                    <varlistentry>
-                        <term><constant>UPDATE</constant></term>
-                        <listitem>
-                            <para>The user may change the properties of this 
object.</para>
-                            <para>In the case of users, this means the user's 
password can be
-                                altered. <emphasis>Permissions are not 
considered properties of a
-                                    user</emphasis>, nor objects in their own 
right, but rather
-                                associations between a user and an action 
which may involve another
-                                object.</para>
-                            <para>The properties of a connection include its 
name, protocol, parent
-                                connection group, and parameters. The 
properties of a connection
-                                group include its name, type, parent 
connection group, and children.
-                                The properties of a sharing profile include 
its name, primary
-                                connection, and parameters.</para>
-                        </listitem>
-                    </varlistentry>
-                </variablelist>
-            </section>
+            <title xml:id="ext-system-permissions">System permissions</title>
+            <para>System permissions describe access to operations that 
manipulate the system as a
+                whole, rather than specific objects. This includes the 
creation of new objects, as
+                object creation directly affects the system, and per-object 
controls cannot exist
+                before the object is actually created.</para>
+            <variablelist>
+                <varlistentry>
+                    <term><constant>ADMINISTER</constant></term>
+                    <listitem>
+                        <para>The user is a super-user - the Guacamole 
equivalent of root. They are
+                            allowed to manipulate of system-level permissions 
and all other objects.
+                            This permission implies all others.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><constant>CREATE_CONNECTION</constant></term>
+                    <listitem>
+                        <para>The user is allowed to create new connections. 
If a user has this
+                            permission, the management interface will display 
components related to
+                            connection creation.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><constant>CREATE_CONNECTION_GROUP</constant></term>
+                    <listitem>
+                        <para>The user is allowed to create new connection 
groups. If a user has
+                            this permission, the management interface will 
display components
+                            related to connection group creation.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><constant>CREATE_SHARING_PROFILE</constant></term>
+                    <listitem>
+                        <para>The user is allowed to create new sharing 
profiles. If a user has this
+                            permission, the management interface will display 
components related to
+                            sharing profile creation.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><constant>CREATE_USER</constant></term>
+                    <listitem>
+                        <para>The user is allowed to create other users. If a 
user has this
+                            permission, the management interface will display 
components related to
+                            user creation.</para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
         </section>
         <section>
-            <title>Connections and history</title>
-            <para>Authentication modules must return 
<classname>Connection</classname> objects which
-                each implement a <methodname>connect()</methodname> function. 
When this function is
-                called, the connection must be made if permission is 
available.</para>
-            <para>This new separation of concerns makes more sense when you
-                consider that as connecting is an operation on a
-                    <classname>Connection</classname>, access to performing 
that
-                operation must be restricted through the
-                    <classname>AuthenticationProvider</classname>, and thus 
must
-                be enforced within the
-                    <classname>AuthenticationProvider</classname>. This
-                separation also opens the door for things like load balancing 
of
-                connections and restricting concurrent access to
-                connections.</para>
-            <para>When a connection is made or terminated, it is also the duty
-                of the authentication module to maintain the connection 
history.
-                Each connection has a corresponding list of
-                    <classname>ConnectionRecord</classname> objects, each of
-                which is associated with a past connection or a 
currently-active
-                connection. This information will ultimately be exposed to the
-                user as a history list when they view a connection in the
-                management interface or as a simple active user count on the
-                connection, advising the user of existing activity.</para>
+            <title xml:id="ext-object-permissions">Object permissions</title>
+            <para>Object permissions describe access to operations that affect 
a particular object.
+                Guacamole currently defines four types of objects which can be 
associated with
+                permissions: users, connections, connection groups, and 
sharing profiles. Each
+                object permission associates a single user with an action that 
may be performed on a
+                single object.</para>
+            <variablelist>
+                <varlistentry>
+                    <term><constant>ADMINISTER</constant></term>
+                    <listitem>
+                        <para>The user may grant or revoke permissions 
involving this object.
+                            "Involving", in this case, refers to either side 
of the permission
+                            association, and includes both the user to whom 
the permission is
+                            granted and the object the permission 
affects.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><constant>DELETE</constant></term>
+                    <listitem>
+                        <para>The user may delete this object. This is 
distinct from the
+                                <constant>ADMINISTER</constant> permission 
which deals only with
+                            permissions. A user with this permission will see 
the "Delete" button
+                            when applicable.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><constant>READ</constant></term>
+                    <listitem>
+                        <para>The user may see that this object exists and 
read the properties of
+                            that object.</para>
+                        <para>Note that the implementation is <emphasis>not 
required to divulge the
+                                true underlying properties of any 
object</emphasis>. The parameters
+                            of a connection or sharing profile, the type or 
contents of a connection
+                            group, the password of a user, etc. all need not 
be exposed.</para>
+                        <para>This is particularly important from the 
perspective of security when
+                            it comes to connections, as the parameters of a 
connection are only
+                            truly needed when a connection is being modified, 
and likely should not
+                            be exposed otherwise. The actual connection 
operation is always
+                            performed internally by the authentication 
provider, and thus does not
+                            require client-side knowledge of anything beyond 
the connection's
+                            existence.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term><constant>UPDATE</constant></term>
+                    <listitem>
+                        <para>The user may change the properties of this 
object.</para>
+                        <para>In the case of users, this means the user's 
password can be altered.
+                                <emphasis>Permissions are not considered 
properties of a
+                                user</emphasis>, nor objects in their own 
right, but rather
+                            associations between a user and an action which 
may involve another
+                            object.</para>
+                        <para>The properties of a connection include its name, 
protocol, parent
+                            connection group, and parameters. The properties 
of a connection group
+                            include its name, type, parent connection group, 
and children. The
+                            properties of a sharing profile include its name, 
primary connection,
+                            and parameters.</para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
         </section>
     </section>
+    <section xml:id="ext-connections">
+        <title>Connections</title>
+        <para>Guacamole connections are organized in a hierarchy made up of 
connection groups, which
+            each act as folders organizing the connections themselves. The 
hierarchy is accessed
+            through the root-level connection group, exposed by
+                <methodname>getRootConnectionGroup()</methodname> by the
+                <classname>UserContext</classname>. The connections and 
connection groups exposed
+            beneath the root connection group must also be accessible directly 
through the
+            connection and connection group directories exposed by
+                <methodname>getConnectionDirectory()</methodname> and
+                <methodname>getConnectionGroupDirectory()</methodname> of the
+                <classname>UserContext</classname>.</para>
+        <para>When a user attempts to use a connection the 
<methodname>connect()</methodname> of the
+            associated <classname>Connection</classname> object will be 
invoked. It is then up to
+            the implementation of this function to establish the TCP 
connection to guacd, perform
+            the connection handshake (most likely via an 
<classname>InetGuacamoleSocket</classname>
+            wrapped within a 
<classname>ConfiguredGuacamoleSocket</classname>), and then return a
+                <classname>GuacamoleTunnel</classname> which controls access 
to the established
+            socket.</para>
+        <para>Extensions may maintain historical record of connection use via
+                <classname>ConnectionRecord</classname> objects, which are 
exposed both at the
+                <classname>Connection</classname> level and across all 
connections via the
+                <classname>UserContext</classname>. Such record maintenance is 
optional, and it is
+            expected that most implementations will simply return empty 
lists.</para>
+        <important>
+            <para>If connection state will not be tracked by the extension, 
and the parameters
+                associated with the connection will be known at the time the 
connection object is
+                created, the <classname>SimpleConnection</classname> 
implementation of
+                    <classname>Connection</classname> can be used to make life 
easier.</para>
+        </important>
+    </section>
 </chapter>


Reply via email to