You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by vn...@apache.org on 2018/11/11 02:23:43 UTC
[1/4] guacamole-manual git commit: GUACAMOLE-220: Document
configuration of LDAP for user groups.
Repository: guacamole-manual
Updated Branches:
refs/heads/master 521492c4a -> 810a6e2a2
GUACAMOLE-220: Document configuration of LDAP for user groups.
Project: http://git-wip-us.apache.org/repos/asf/guacamole-manual/repo
Commit: http://git-wip-us.apache.org/repos/asf/guacamole-manual/commit/05bc901b
Tree: http://git-wip-us.apache.org/repos/asf/guacamole-manual/tree/05bc901b
Diff: http://git-wip-us.apache.org/repos/asf/guacamole-manual/diff/05bc901b
Branch: refs/heads/master
Commit: 05bc901b6b88c6bc47270edfe0783f715eb07bc3
Parents: cc2da2e
Author: Michael Jumper <mj...@apache.org>
Authored: Sat Nov 3 15:03:43 2018 -0700
Committer: Michael Jumper <mj...@apache.org>
Committed: Sat Nov 3 15:03:43 2018 -0700
----------------------------------------------------------------------
src/chapters/ldap-auth.xml | 15 +++++++++++++--
1 file changed, 13 insertions(+), 2 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/05bc901b/src/chapters/ldap-auth.xml
----------------------------------------------------------------------
diff --git a/src/chapters/ldap-auth.xml b/src/chapters/ldap-auth.xml
index 97dc84c..aa4291f 100644
--- a/src/chapters/ldap-auth.xml
+++ b/src/chapters/ldap-auth.xml
@@ -385,8 +385,9 @@ dn: cn={4}guacConfigGroup,cn=schema,cn=config
<varlistentry>
<term><property>ldap-group-base-dn</property></term>
<listitem>
- <para>The base of the DN for all groups that may be referenced within
- Guacamole configurations using the standard <property>seeAlso</property>
+ <para>The base of the DN for all user groups that may be used by other
+ extensions to define permissions or that may referenced within Guacamole
+ configurations using the standard <property>seeAlso</property>
attribute. All groups which will be used to control access to Guacamole
configurations must be descendents of this base DN. <emphasis>If this
property is omitted, the <property>seeAlso</property> attribute will
@@ -394,6 +395,16 @@ dn: cn={4}guacConfigGroup,cn=schema,cn=config
</listitem>
</varlistentry>
<varlistentry>
+ <term><property>ldap-group-name-attribute</property></term>
+ <listitem>
+ <para>The attribute or attributes which define the unique name of user
+ groups in the LDAP directory. Usually, and by default, this will simply
+ be "<property>cn</property>". If your LDAP directory contains groups
+ whose names are dictated by different attributes, multiple attributes
+ can be specified here, separated by commas.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><property>ldap-dereference-aliases</property></term>
<listitem>
<para>Controls whether or not the LDAP connection follows (dereferences) aliases
[3/4] guacamole-manual git commit: GUACAMOLE-220: Merge document LDAP
support for user groups.
Posted by vn...@apache.org.
GUACAMOLE-220: Merge document LDAP support for user groups.
Project: http://git-wip-us.apache.org/repos/asf/guacamole-manual/repo
Commit: http://git-wip-us.apache.org/repos/asf/guacamole-manual/commit/d7d23bf0
Tree: http://git-wip-us.apache.org/repos/asf/guacamole-manual/tree/d7d23bf0
Diff: http://git-wip-us.apache.org/repos/asf/guacamole-manual/diff/d7d23bf0
Branch: refs/heads/master
Commit: d7d23bf042970686e2ca2d9baa0e26276edda310
Parents: 08a08aa 2ac4851
Author: Nick Couchman <vn...@apache.org>
Authored: Sat Nov 10 21:22:29 2018 -0500
Committer: Nick Couchman <vn...@apache.org>
Committed: Sat Nov 10 21:22:29 2018 -0500
----------------------------------------------------------------------
src/chapters/jdbc-auth.xml | 15 +++----
src/chapters/ldap-auth.xml | 93 +++++++++++++++++++++++++----------------
2 files changed, 64 insertions(+), 44 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/d7d23bf0/src/chapters/jdbc-auth.xml
----------------------------------------------------------------------
[4/4] guacamole-manual git commit: Merge 1.0.0 changes back to master.
Posted by vn...@apache.org.
Merge 1.0.0 changes back to master.
Project: http://git-wip-us.apache.org/repos/asf/guacamole-manual/repo
Commit: http://git-wip-us.apache.org/repos/asf/guacamole-manual/commit/810a6e2a
Tree: http://git-wip-us.apache.org/repos/asf/guacamole-manual/tree/810a6e2a
Diff: http://git-wip-us.apache.org/repos/asf/guacamole-manual/diff/810a6e2a
Branch: refs/heads/master
Commit: 810a6e2a20ed63c88869b4a9e0b7e27dd2f0bebe
Parents: 521492c d7d23bf
Author: Nick Couchman <vn...@apache.org>
Authored: Sat Nov 10 21:23:22 2018 -0500
Committer: Nick Couchman <vn...@apache.org>
Committed: Sat Nov 10 21:23:22 2018 -0500
----------------------------------------------------------------------
src/chapters/jdbc-auth.xml | 15 +++----
src/chapters/ldap-auth.xml | 93 +++++++++++++++++++++++++----------------
2 files changed, 64 insertions(+), 44 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/810a6e2a/src/chapters/ldap-auth.xml
----------------------------------------------------------------------
diff --cc src/chapters/ldap-auth.xml
index d9f09e9,e1b4522..3c47567
--- a/src/chapters/ldap-auth.xml
+++ b/src/chapters/ldap-auth.xml
@@@ -357,72 -360,11 +360,72 @@@ dn: cn={4}guacConfigGroup,cn=schema,cn=
</listitem>
</varlistentry>
<varlistentry>
+ <term><property>ldap-user-attributes</property></term>
+ <listitem>
+ <para>The attribute or attributes to retrieve from the LDAP directory for
+ the currently logged-in user, separated by commas. If specified, the
+ attributes listed here are retrieved from each authenticated user and
+ dynamically applied to the parameters of that user's connections as
+ <link linkend="parameter-tokens">parameter tokens</link> with the
+ prefix "<varname>LDAP_</varname>".</para>
+ <para>When a user authenticates with LDAP and accesses a particular
+ Guacamole connection, the values of these tokens will be the values of
+ their corresponding attributes at the time of authentication. If the
+ attribute has no value for the current user, then the corresponding
+ token is not applied. If the attribute has multiple values, then the
+ first value of the attribute is used.</para>
+ <para>When converting an LDAP attribute name into a parameter token name,
+ the name of the attribute is transformed into uppercase with each word
+ separated by underscores, a naming convention referred to as "uppercase
+ with underscores" or "<link
+ xlink:href="https://en.wikipedia.org/wiki/Naming_convention_(programming)#Multiple-word_identifiers"
+ >screaming snake case</link>". For example:</para>
+ <table frame="all">
+ <title>Example LDAP attribute / parameter token conversions</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1.0*"/>
+ <colspec colname="c2" colnum="2" colwidth="1.0*"/>
+ <thead>
+ <row>
+ <entry>LDAP Attribute</entry>
+ <entry>Parameter Token</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><varname>lowercase-with-dashes</varname></entry>
+ <entry><varname>${LDAP_LOWERCASE_WITH_DASHES}</varname></entry>
+ </row>
+ <row>
+ <entry><varname>CamelCase</varname></entry>
+ <entry><varname>${LDAP_CAMEL_CASE}</varname></entry>
+ </row>
+ <row>
+ <entry><varname>headlessCamelCase</varname></entry>
+ <entry><varname>${LDAP_HEADLESS_CAMEL_CASE}</varname></entry>
+ </row>
+ <row>
+ <entry><varname>lettersAndNumbers1234</varname></entry>
+ <entry><varname>${LDAP_LETTERS_AND_NUMBERS_1234}</varname></entry>
+ </row>
+ <row>
+ <entry><varname>aRANDOM_mixOf-3NAMINGConventions</varname></entry>
+ <entry><varname>${LDAP_A_RANDOM_MIX_OF_3_NAMING_CONVENTIONS}</varname></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>Usage of parameter tokens is discussed in more detail in <xref
+ linkend="configuring-guacamole"/> in <xref
+ linkend="parameter-tokens"/>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><property>ldap-user-search-filter</property></term>
<listitem>
- <para>The search filter used to query the LDAP tree for users that
- can log into and be granted privileges in Guacamole. <emphasis>If
- this property is omitted the default of "(objectClass=*)" will be used.
+ <para>The search filter used to query the LDAP tree for users that can log
+ into and be granted privileges in Guacamole. <emphasis>If this property
+ is omitted the default of "(objectClass=*)" will be used.
</emphasis></para>
</listitem>
</varlistentry>
[2/4] guacamole-manual git commit: GUACAMOLE-220: Document using LDAP
with a database with respect to user groups.
Posted by vn...@apache.org.
GUACAMOLE-220: Document using LDAP with a database with respect to user groups.
Project: http://git-wip-us.apache.org/repos/asf/guacamole-manual/repo
Commit: http://git-wip-us.apache.org/repos/asf/guacamole-manual/commit/2ac48510
Tree: http://git-wip-us.apache.org/repos/asf/guacamole-manual/tree/2ac48510
Diff: http://git-wip-us.apache.org/repos/asf/guacamole-manual/diff/2ac48510
Branch: refs/heads/master
Commit: 2ac48510d475bb3b5eba0664c05c7a2cfe5cd624
Parents: 05bc901
Author: Michael Jumper <mj...@apache.org>
Authored: Sun Nov 4 21:53:38 2018 -0800
Committer: Michael Jumper <mj...@apache.org>
Committed: Sun Nov 4 21:53:38 2018 -0800
----------------------------------------------------------------------
src/chapters/jdbc-auth.xml | 15 ++++----
src/chapters/ldap-auth.xml | 78 +++++++++++++++++++++++------------------
2 files changed, 51 insertions(+), 42 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/2ac48510/src/chapters/jdbc-auth.xml
----------------------------------------------------------------------
diff --git a/src/chapters/jdbc-auth.xml b/src/chapters/jdbc-auth.xml
index eca6b58..fe1f405 100644
--- a/src/chapters/jdbc-auth.xml
+++ b/src/chapters/jdbc-auth.xml
@@ -19,13 +19,14 @@
changes to users and connections take effect immediately; users need not logout and back in
to see new connections.</para>
<para>While most authentication extensions function independently, the database authentication
- can act in a subordinate role, allowing users from other authentication extensions to be
- associated with connections within the database. Users are considered identical to users
- within the database if they have the same usernames, and the authentication result of
- another extension will be trusted if it succeeds. A user with an account under multiple
- systems will thus be able to see data from each system after successfully logging in. For
- more information on using the database authentication alongside other mechanisms, see <xref
- linkend="ldap-and-database"/> within <xref linkend="ldap-auth"/>.</para>
+ can act in a subordinate role, allowing users and user groups from other authentication
+ extensions to be associated with connections within the database. Users and groups are
+ considered identical to those within the database if they have the same names, and the
+ authentication result of another extension will be trusted if it succeeds. A user with an
+ account under multiple systems will thus be able to see data from each system after
+ successfully logging in. For more information on using the database authentication alongside
+ other mechanisms, see <xref linkend="ldap-and-database"/> within <xref linkend="ldap-auth"
+ />.</para>
<para>To use the database authentication extension, you will need:</para>
<orderedlist>
<listitem>
http://git-wip-us.apache.org/repos/asf/guacamole-manual/blob/2ac48510/src/chapters/ldap-auth.xml
----------------------------------------------------------------------
diff --git a/src/chapters/ldap-auth.xml b/src/chapters/ldap-auth.xml
index aa4291f..e1b4522 100644
--- a/src/chapters/ldap-auth.xml
+++ b/src/chapters/ldap-auth.xml
@@ -182,23 +182,26 @@ dn: cn={4}guacConfigGroup,cn=schema,cn=config
</section>
<section xml:id="ldap-and-database">
<title>Associating LDAP with a database</title>
- <para>If you install both the LDAP authentication as well as support for MySQL or PostgreSQL
+ <para>If you install both the LDAP authentication as well as support for a database
(following the instructions in <xref linkend="jdbc-auth"/>), Guacamole will
automatically attempt to authenticate against both systems whenever a user attempts to
- log in. That user will have access to any data associated with them via the database, as
- well as any visible objects within the LDAP directory. The LDAP account will be
- considered equivalent to the database user if the username is identical.</para>
- <para>Data can be manually associated with LDAP users by creating corresponding user
- accounts within the database which each have the same usernames as valid LDAP users. As
- long as the username is identical, a successful login attempt against LDAP will be
- trusted by the database authentication, and that user's associated data will be
- visible.</para>
+ log in. In addition to any visible objects within the LDAP directory, that user will
+ have access to any data associated with their account in the database, as well as any
+ data associated with user groups that they belong to. LDAP user accounts and groups will
+ be considered equivalent to database users and groups if their unique names are
+ identical, as determined by the attributes given for <link linkend="guac-ldap-config"
+ >the <property>ldap-username-attribute</property> and
+ <property>ldap-group-name-attribute</property> properties</link>.</para>
+ <para>Data can be manually associated with LDAP user accounts or groups by creating
+ corresponding users or groups within the database which each have the same names. As
+ long as the names are identical, a successful login attempt against LDAP will be trusted
+ by the database authentication, and that user's associated data will be visible.</para>
<para>If an administrator account (such as the default <systemitem>guacadmin</systemitem>
user provided with the database authentication) has a corresponding user in the LDAP
- directory with permission to list and read other LDAP users, the Guacamole
- administrative interface will include LDAP users in the overall user list presented to
- the administrator, and allow connections from the database to be associated with those
- users directly.</para>
+ directory with permission to read other LDAP users and groups, the Guacamole
+ administrative interface will include them in the lists presented to the administrator,
+ and will allow connections from the database to be associated with those users or groups
+ directly.</para>
</section>
<section xml:id="installing-ldap-auth">
<title>Installing LDAP authentication</title>
@@ -225,7 +228,7 @@ dn: cn={4}guacConfigGroup,cn=schema,cn=config
configure the LDAP authentication properly, Guacamole will not start up again until
the configuration is fixed.</para>
</important>
- <section>
+ <section xml:id="guac-ldap-config">
<title>Configuring Guacamole for LDAP</title>
<indexterm>
<primary>configuring LDAP</primary>
@@ -339,7 +342,7 @@ dn: cn={4}guacConfigGroup,cn=schema,cn=config
<listitem>
<para>The attribute or attributes which contain the username within all
Guacamole user objects in the LDAP directory. Usually, and by default,
- this will simply be "<property>uid</property>". If your LDAP directory
+ this will simply be "<property>uid</property>". If your LDAP directory
contains users whose usernames are dictated by different attributes,
multiple attributes can be specified here, separated by commas, but
beware: <emphasis>doing so requires that a search DN be provided with
@@ -359,9 +362,9 @@ dn: cn={4}guacConfigGroup,cn=schema,cn=config
<varlistentry>
<term><property>ldap-user-search-filter</property></term>
<listitem>
- <para>The search filter used to query the LDAP tree for users that
- can log into and be granted privileges in Guacamole. <emphasis>If
- this property is omitted the default of "(objectClass=*)" will be used.
+ <para>The search filter used to query the LDAP tree for users that can log
+ into and be granted privileges in Guacamole. <emphasis>If this property
+ is omitted the default of "(objectClass=*)" will be used.
</emphasis></para>
</listitem>
</varlistentry>
@@ -407,33 +410,38 @@ dn: cn={4}guacConfigGroup,cn=schema,cn=config
<varlistentry>
<term><property>ldap-dereference-aliases</property></term>
<listitem>
- <para>Controls whether or not the LDAP connection follows (dereferences) aliases
- as it searches the tree. Possible values for this property are "never" (the default)
- so that aliases will never be followed, "searching" to dereference during search operations
- after the base object is located, "finding" to dereference in order to locate the
- search base, but not during the actual search, and "always" to always dereference
- aliases.</para>
+ <para>Controls whether or not the LDAP connection follows (dereferences)
+ aliases as it searches the tree. Possible values for this property are
+ "never" (the default) so that aliases will never be followed,
+ "searching" to dereference during search operations after the base
+ object is located, "finding" to dereference in order to locate the
+ search base, but not during the actual search, and "always" to always
+ dereference aliases.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>ldap-follow-referrals</property></term>
<listitem>
- <para>This option controls whether or not the LDAP module follow referrals when
- processing search results from a LDAP search. Referrals can be pointers to other
- parts of an LDAP tree, or to a different server/connection altogether. This is a boolean
- parameter, with valid options of "true" or "false." The default is false. When disabled,
- LDAP referrals will be ignored when encounterd by the Guacamole LDAP client and the client
- will move on to the next result. When enabled, the LDAP client will follow the referral and
- process results within the referral, subject to the maximum hops parameter below.</para>
+ <para>This option controls whether or not the LDAP module follow referrals
+ when processing search results from a LDAP search. Referrals can be
+ pointers to other parts of an LDAP tree, or to a different
+ server/connection altogether. This is a boolean parameter, with valid
+ options of "true" or "false." The default is false. When disabled, LDAP
+ referrals will be ignored when encounterd by the Guacamole LDAP client
+ and the client will move on to the next result. When enabled, the LDAP
+ client will follow the referral and process results within the referral,
+ subject to the maximum hops parameter below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><property>ldap-max-referral-hops</property></term>
<listitem>
- <para>This option controls the maximum number of referrals that will be processed before the
- LDAP client refuses to follow any more referrals. The default is 5. If the ldap-follow-referrals
- property is set to false (the default), this option has no effect. If the ldap-follow-referrals option
- is set to true, this will limit the depth of referrals followed to the number specified.</para>
+ <para>This option controls the maximum number of referrals that will be
+ processed before the LDAP client refuses to follow any more referrals.
+ The default is 5. If the ldap-follow-referrals property is set to false
+ (the default), this option has no effect. If the ldap-follow-referrals
+ option is set to true, this will limit the depth of referrals followed
+ to the number specified.</para>
</listitem>
</varlistentry>
<varlistentry>