You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by jm...@apache.org on 2016/10/17 23:45:16 UTC
[1/4] incubator-guacamole-manual git commit: GUACAMOLE-88: Document
sharing profile permissions.
Repository: incubator-guacamole-manual
Updated Branches:
refs/heads/master e787d0536 -> b5ecd9985
GUACAMOLE-88: Document sharing profile permissions.
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/93fff046
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/93fff046
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/93fff046
Branch: refs/heads/master
Commit: 93fff046176b53dc18b8fd16b63a01e892998346
Parents: e787d05
Author: Michael Jumper <mj...@apache.org>
Authored: Sat Oct 15 22:22:20 2016 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Sat Oct 15 22:22:20 2016 -0700
----------------------------------------------------------------------
src/chapters/guacamole-ext.xml | 35 +++++++++++++++++++++--------------
1 file changed, 21 insertions(+), 14 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/93fff046/src/chapters/guacamole-ext.xml
----------------------------------------------------------------------
diff --git a/src/chapters/guacamole-ext.xml b/src/chapters/guacamole-ext.xml
index d7904f2..25216da 100644
--- a/src/chapters/guacamole-ext.xml
+++ b/src/chapters/guacamole-ext.xml
@@ -567,8 +567,7 @@
<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, such as the "Manage" and "New Connection"
- buttons.</para>
+ to connection creation.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -576,8 +575,15 @@
<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, such as the "Manage" and "New
- Group" buttons.</para>
+ 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>
@@ -585,8 +591,7 @@
<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, such as the "Manage" and "New User"
- buttons.</para>
+ to user creation.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -594,10 +599,10 @@
<section>
<title>Object permissions</title>
<para>Object permissions describe access to operations that affect a particular
- object. Guacamole currently defines three types of objects which can be
- associated with permissions: users, connections, and connection groups. Each
- object permission associates a single user with an action that may be performed
- on a single object.</para>
+ 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>
@@ -624,8 +629,9 @@
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, the type or contents of a connection
- group, the password of a user, etc. all need not be exposed.</para>
+ 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
@@ -646,8 +652,9 @@
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.</para>
+ 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>
[2/4] incubator-guacamole-manual git commit: GUACAMOLE-88: Expand
documentation covering authentication process.
Posted by jm...@apache.org.
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 <mj...@apache.org>
Authored: Sun Oct 16 13:47:52 2016 -0700
Committer: Michael Jumper <mj...@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>
[3/4] incubator-guacamole-manual git commit: GUACAMOLE-88: Describe
connection share process.
Posted by jm...@apache.org.
GUACAMOLE-88: Describe connection share 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/7787ddc7
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/7787ddc7
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/7787ddc7
Branch: refs/heads/master
Commit: 7787ddc7e74f3c4e765fa9b6d78378e019194725
Parents: 1962038
Author: Michael Jumper <mj...@apache.org>
Authored: Sun Oct 16 14:08:26 2016 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Sun Oct 16 14:08:26 2016 -0700
----------------------------------------------------------------------
src/chapters/guacamole-ext.xml | 57 +++++++++++++++++++++++++++++++++++++
1 file changed, 57 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/blob/7787ddc7/src/chapters/guacamole-ext.xml
----------------------------------------------------------------------
diff --git a/src/chapters/guacamole-ext.xml b/src/chapters/guacamole-ext.xml
index 98983a6..2697dbe 100644
--- a/src/chapters/guacamole-ext.xml
+++ b/src/chapters/guacamole-ext.xml
@@ -717,4 +717,61 @@
<classname>Connection</classname> can be used to make life easier.</para>
</important>
</section>
+ <section xml:id="ext-active-connections">
+ <title>Managing/sharing active connections</title>
+ <para>After a connection has been established, its underlying
+ <classname>GuacamoleTunnel</classname> can be exposed by a
+ <classname>UserContext</classname> through the <classname>Directory</classname>
+ returned by <methodname>getActiveConnectionDirectory()</methodname>. The
+ <classname>ActiveConnection</classname> objects accessible through this
+ <classname>Directory</classname> are the means by which an administrator may monitor
+ or forcibly terminate another user's connection, ultimately resulting in Guacamole
+ invoking the <methodname>close()</methodname> function of the underlying
+ <classname>GuacamoleTunnel</classname>, and also serve as the basis for screen
+ sharing.</para>
+ <para>Screen sharing is implemented through the use of <classname>SharingProfile</classname>
+ objects, exposed through yet another <classname>Directory</classname> beneath the
+ <classname>UserContext</classname>. Each sharing profile is associated with a single
+ connection that it can be used to share, referred to as the "primary connection". If a
+ user has read access to a sharing profile associated with their current connection, that
+ sharing profile will be displayed as an option within <link
+ xmlns:xlink="http://www.w3.org/1999/xlink" linkend="client-share-menu">the share
+ menu of the Guacamole menu</link>.</para>
+ <para>The overall sharing process is as follows:</para>
+ <orderedlist>
+ <listitem>
+ <para>A user, having access to a sharing profile associated with their current
+ active connection, clicks its option within the <link
+ xmlns:xlink="http://www.w3.org/1999/xlink" linkend="client-share-menu">share
+ menu</link>.</para>
+ </listitem>
+ <listitem>
+ <para>Guacamole locates the <classname>ActiveConnection</classname> and invokes its
+ <methodname>getSharingCredentials()</methodname> function with the
+ identifier of the sharing profile. The contents of the returned
+ <classname>UserCredentials</classname> object is used by Guacamole to
+ generate a sharing link which can be given to other users.</para>
+ </listitem>
+ <listitem>
+ <para>When another user visits the sharing link, the credentials embedded in the
+ link are passed to the authentication providers associated with each installed
+ extension. <emphasis>It is up to the extension that originally provided those
+ credentials to authenticate the user and provide them with access to the
+ shared connection.</emphasis></para>
+ </listitem>
+ <listitem>
+ <para>When the user attempts to connect to the shared connection, the extension
+ establishes the connection using the ID of the connection being joined.
+ <emphasis>This is not the connection identifier as dictated by
+ guacamole-ext, but rather <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ linkend="guacamole-protocol-joining">the unique ID assigned by guacd as
+ required by the Guacamole protocol</link>.</emphasis> This ID can be
+ retrieved from a <methodname>ConfiguredGuacamoleSocket</methodname> via
+ <methodname>getConnectionID()</methodname>, and can be passed through a
+ <methodname>GuacamoleConfiguration</methodname> through
+ <methodname>setConnectionID()</methodname> (instead of specifying a
+ protocol, as would be done for a brand new connection).</para>
+ </listitem>
+ </orderedlist>
+ </section>
</chapter>
[4/4] incubator-guacamole-manual git commit: GUACAMOLE-88: Merge
documentation for screen sharing and other minor improvements."
Posted by jm...@apache.org.
GUACAMOLE-88: Merge documentation for screen sharing and other minor improvements."
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/b5ecd998
Tree: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/tree/b5ecd998
Diff: http://git-wip-us.apache.org/repos/asf/incubator-guacamole-manual/diff/b5ecd998
Branch: refs/heads/master
Commit: b5ecd9985c89fa485368eb477e14a75f97b9fccf
Parents: e787d05 7787ddc
Author: James Muehlner <ja...@guac-dev.org>
Authored: Mon Oct 17 16:44:31 2016 -0700
Committer: James Muehlner <ja...@guac-dev.org>
Committed: Mon Oct 17 16:44:31 2016 -0700
----------------------------------------------------------------------
src/chapters/guacamole-ext.xml | 607 +++++++++++++++++++++---------------
1 file changed, 351 insertions(+), 256 deletions(-)
----------------------------------------------------------------------