GUACAMOLE-1239: Merge documentation for configuring username case sensitivity.
diff --git a/src/cas-auth.md b/src/cas-auth.md
index 673b9ce..84c7764 100644
--- a/src/cas-auth.md
+++ b/src/cas-auth.md
@@ -57,7 +57,7 @@
: The URI to redirect back to upon successful authentication. Normally this
will be the full URL of your Guacamole installation.
-Additional optional properties are available to control how CAS tokens are
+Additional optional properties are available to control how CAS-related data is
processed, including whether [CAS ClearPass](cas-clearpass) should be used and
how user group memberships should be derived:
@@ -98,6 +98,16 @@
This property has no effect if cas-group-format is not `ldap`.
+`cas-case-sensitive-usernames`
+: "true" if the CAS extension should be configured to treat usernames as
+ case-sensitive, otherwise false. By default this will pull the
+ [global configuration value for case-sensitivity for Guacamole usernames](global-case-sensitive-usernames).
+
+ Please note that changing the value of this option will not change
+ how the CAS server itself processes usernames, so it is important
+ to make sure that this value matches how you expect the CAS server
+ to treat usernames with respect to case.
+
(cas-login)=
### Controlling login behavior
diff --git a/src/configuring-guacamole.md b/src/configuring-guacamole.md
index 80bf61b..3662bf7 100644
--- a/src/configuring-guacamole.md
+++ b/src/configuring-guacamole.md
@@ -131,6 +131,32 @@
them, nor will they be used automatically based on local browser language.
If omitted, all defined languages will be available.
+(global-case-sensitive-usernames)=
+`case-sensitive-usernames`
+: If set to "true", Guacamole will treat usernames as case-sensitive, and
+ comparisons between usernames will take differences in case into account -
+ for example, "john_smith" will be considered a different user than
+ "John_Smith". If set to "false", Guacamole will not take case into
+ account when processing and comparing usernames.
+
+ In keeping with the behavior of Guacamole prior to the introduction of this
+ configuration property, this will default to "true", and case differences
+ in usernames will be considered.
+
+ This option sets the global/default setting across the entire Guacamole
+ install, but many of the extensions that provide an authentication mechanism
+ for users have matching options that can override this behavior on a per-
+ extension basis. See the documentation for the various authentication
+ extensions for the exact property for the extension.
+
+ Finally, whether or not various authentication systems actually process
+ usernames in a case-sensitive manner is somewhat out of the control
+ of Guacamole. For example, most LDAP directories do not factor case
+ into usernames, and setting this option to true will not suddenly force
+ your LDAP directory into case-sensitive comparisons. This option controls
+ how Guacamole handles usernames of various cases, not necessarily the
+ underlying authentication mechanism.
+
`enable-environment-properties`
: If set to "true", Guacamole will first evaluate its environment to obtain
the value for any given configuration property, before using a value
diff --git a/src/header-auth.md b/src/header-auth.md
index 904fa89..247614f 100644
--- a/src/header-auth.md
+++ b/src/header-auth.md
@@ -55,7 +55,10 @@
The HTTP header authentication extension provides only one configuration
property, and it is optional. By default, the extension will pull the username
-of the authenticated user from the `REMOTE_USER` header, if present. If your
+of the authenticated user from the `REMOTE_USER` header, if present. The header
+module has a couple of options available to help configure it to suit your
+particular environment:
+If your
authentication system uses a different HTTP header, you will need to override
this by specifying the `http-auth-header` property within
[`guacamole.properties`](initial-setup):
@@ -63,7 +66,15 @@
`http-auth-header`
: The HTTP header containing the username of the authenticated user. This
property is optional. If not specified, `REMOTE_USER` will be used by
- default.
+ default. If your authentication system uses a different HTTP header you
+ can use this option to override it and specify the header for Guacamole
+ to expect.
+
+`http-auth-case-sensitive-usernames`
+: Whether or not the header module, specifically, should treat usernames as
+ case sensitive or not. This option defaults to the
+ [global default set for the entire Guacamole installation](global-case-sensitive-usernames),
+ but can be overridden for the header module, if desired.
(completing-header-install)=
diff --git a/src/jdbc-auth.md b/src/jdbc-auth.md
index 2beb5dd..ee80417 100644
--- a/src/jdbc-auth.md
+++ b/src/jdbc-auth.md
@@ -386,6 +386,15 @@
database. This is given as "guacamole_user" in the examples given in this
chapter.
+`mysql-case-sensitive-usernames`
+: "true" if the MySQL extension should evaluate usernames in a case-sensitive
+ fashion, otherwise false. This defaults to the overall
+ [global setting of the Guacamole install](global-case-sensitive-usernames).
+ It is worth noting, however, that MySQL's default database collation does
+ not support case-sensitive string comparisons, which means that additional
+ configuration would be required on the database to truly make this
+ extension behave in case-sensitive manner.
+
`mysql-password`
: The password Guacamole should provide when authenticating with the database.
This is given as "some_password" in the examples given in this chapter.
@@ -404,6 +413,15 @@
database. This is given as "guacamole_user" in the examples given in this
chapter.
+`postgresql-case-sensitive-usernames`
+: "true" if the PostgreSQL extension should evaluate usernames in a case-sensitive
+ fashion, otherwise false. This will default to the overall
+ [global setting of the Guacamole install](global-case-sensitive-usernames).
+ By default the PostgreSQL database performs case-sensitive string comparisons,
+ so, if this is set to "true", either explicitly or because the Guacamole
+ global setting is "true", the PostgreSQL extension will honor case when
+ authenticating users.
+
`postgresql-password`
: The password Guacamole should provide when authenticating with the database.
This is given as "some_password" in the examples given in this chapter.
@@ -422,6 +440,15 @@
database. This is given as "guacamole_user" in the examples given in this
chapter.
+`sqlserver-case-sensitive-usernames`
+: "true" if the SQL Server module should take case into account when
+ checking usernames, otherwise "false". This will default to the overall
+ [global setting for username case sensitivity](global-case-sensitive-usernames).
+ Please note that, by default, SQL Server databases use a collation that does
+ not take case into account when comparing strings, so, even if this option
+ is set to "true", additional configuration may be required on the SQL
+ database to make it behave in a case-sensitive manner.
+
`sqlserver-password`
: The password Guacamole should provide when authenticating with the database.
This is given as "some_password" in the examples given in this chapter.
diff --git a/src/json-auth.md b/src/json-auth.md
index 04a380e..b5ea5f6 100644
--- a/src/json-auth.md
+++ b/src/json-auth.md
@@ -63,6 +63,16 @@
json-secret-key: 4c0b569e4c96df157eee1b65dd0e4d41
+The JSON module also supports the `json-case-sensitive-usernames` property,
+which, if set to "true", will tell the JSON module to treat usernames processed
+through the module in a case-sensitive manner. If set to "false", the module
+will not consider case differences when comparing usernames. It's important
+to note that the underlying system sending the JSON data may or may not treat
+usernames as case-sensitive, so the configuration of this property should
+match the expected behavior of the authentication system. The default for this
+value is inherited from the
+[global Guacamole case-sensitivity setting](global-case-sensitive-usernames).
+
(completing-json-install)=
### Completing the installation
diff --git a/src/ldap-auth.md b/src/ldap-auth.md
index d43f8a9..5116a32 100644
--- a/src/ldap-auth.md
+++ b/src/ldap-auth.md
@@ -401,6 +401,17 @@
be granted privileges in Guacamole. *If this property is omitted the default of
`(objectClass=*)` will be used.*
+`ldap-case-sensitive-usernames`
+: "true" if the LDAP module should be configured to compare and interpret usernames
+ in a case-sensitive manner, otherwise "false". This will default to the
+ [global value configured for the entire Guacamole installation](global-case-sensitive-usernames).
+
+ Note that, while this configures how the LDAP extension behaves with respect
+ to usernames, it cannot impact how the underlying LDAP server handles
+ usernames and whether or not it interprets them case-(in)sensitively. It is
+ a good idea to understand how your LDAP server handles this, and then
+ configure the Guacamole LDAP extension to match.
+
`ldap-config-base-dn`
: The base of the DN for all Guacamole configurations. *This property is
optional.* If omitted, the configurations of Guacamole connections will
diff --git a/src/openid-auth.md b/src/openid-auth.md
index 2c22547..4d99a25 100644
--- a/src/openid-auth.md
+++ b/src/openid-auth.md
@@ -115,6 +115,16 @@
: The claim type within any valid JWT that contains the authenticated user's
username. By default, the "`email`" claim type is used.
+`openid-case-sensitive-usernames`
+: "true" if the OpenID module should treat usernames as case-sensitive,
+ otherwise "false". The default for this value derives from the
+ [global Guacamole configuration for case-sensitive usernames](global-case-sensitive-usernames).
+
+ Please note that changing this value does not change how the OpenID Identity
+ Provider (IdP) processes usernames, so it is important that you make sure
+ that the configured value for this module matches how the OpenID server will
+ treat username case.
+
`openid-groups-claim-type`
: The claim type within any valid JWT that contains the list of groups of which
the authenticated user is a member. By default, the "`groups`" claim type is
diff --git a/src/radius-auth.md b/src/radius-auth.md
index a722b94..6cf7f91 100644
--- a/src/radius-auth.md
+++ b/src/radius-auth.md
@@ -236,6 +236,19 @@
specified, the RADIUS extension attempts to automatically determine the IP
address of the system on which Guacamole is running and uses that value.
+`radius-case-sensitive-usernames`
+: "true" if the RADIUS authentication extension should treat usernames as
+ case sensitive, otherwise "false". The default for this value is inherited
+ from
+ [Guacamole's global configuration for case-sensitivity](global-case-sensitive-usernames),
+ and this property can be used to override that setting specifically for the
+ RADIUS extension.
+
+ It is important to note that changing this setting will not impact how
+ the RADIUS server processes usernames with respect to case-(in)sensitivity,
+ so the setting should be set to match your particular RADIUS server
+ configuration.
+
(completing-radius-install)=
Completing the installation
diff --git a/src/saml-auth.md b/src/saml-auth.md
index edc6668..84ab693 100644
--- a/src/saml-auth.md
+++ b/src/saml-auth.md
@@ -99,6 +99,15 @@
property is optional and will default to true (compression will be
requested).
+`saml-case-sensitive-usernames"
+: "true" if the SAML module will treat usernames as case-sensitive, otherwise
+ "false". The default value for this is taken from the
+ [global Guacamole configuration for username case-sensitivity](global-case-sensitive-usernames).
+
+ Please note that changing this option will not impact how the SAML IdP
+ treats usernames, so it is important that you configure this option to
+ match the expected behavior of the IdP with respect to usernames and case.
+
`saml-group-attribute`
: The name of the attribute provided by the SAML IdP that contains group
membership of the user. These groups will be parsed and used to map group
