guacamole-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jmuehl...@apache.org
Subject [2/4] incubator-guacamole-manual git commit: GUACAMOLE-88: Expand documentation covering authentication process.
Date Mon, 17 Oct 2016 23:45:17 GMT
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 <mjumper@apache.org>
Authored: Sun Oct 16 13:47:52 2016 -0700
Committer: Michael Jumper <mjumper@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>



Mime
View raw message