Merge 1.4.0 changes back to master.

apache · Dec 12, 2021 · 73829a6629bfa547f24419089461c4521d053296 · 73829a6
2 parents d3898b8 + 21a9d2a
commit 73829a6629bfa547f24419089461c4521d053296
Showing 7 changed files with 184 additions and 28 deletions.
diff --git a/src/cas-auth.md b/src/cas-auth.md
@@ -13,14 +13,11 @@ connection information, as it only provides user authentication.
 Downloading the CAS authentication extension
 --------------------------------------------
 
-The CAS authentication extension is available separately from the main
-`guacamole.war`. The link for this and all other officially-supported and
-compatible extensions for a particular version of Guacamole are provided on the
-release notes for that version. You can find the release notes for current
-versions of Guacamole here: <http://guacamole.apache.org/releases/>.
-
-The CAS authentication extension is packaged as a `.tar.gz` file containing
-only the extension itself, `guacamole-auth-cas-1.4.0.jar`, which must
+```{include} include/sso-download.md
+```
+
+The extension for the desired SSO method, in this case
+`guacamole-auth-sso-cas-1.4.0.jar` from within the `cas/` subdirectory, must
 ultimately be placed in `GUACAMOLE_HOME/extensions`.
 
 (installing-cas-auth)=
@@ -38,7 +35,7 @@ To install the CAS authentication extension, you must:
 1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already
    exist.
 
-2. Copy `guacamole-auth-cas-1.4.0.jar` within `GUACAMOLE_HOME/extensions`.
+2. Copy `guacamole-auth-sso-cas-1.4.0.jar` within `GUACAMOLE_HOME/extensions`.
 
 3. Configure Guacamole to use CAS authentication, as described below.
 
@@ -101,6 +98,33 @@ how user group memberships should be derived:
 
   This property has no effect if cas-group-format is not `ldap`.
 
+(cas-login)=
+
+### Controlling login behavior
+
+```{include} include/sso-login-behavior.md
+```
+
+#### Automatically redirecting all unauthenticated users
+
+To ensure users are redirected to the CAS identity provider immediately
+(without a Guacamole login screen), ensure the CAS extension has priority over
+all others:
+
+```
+extension-priority: cas
+```
+
+#### Presenting unauthenticated users with a login screen
+
+To ensure users are given a normal Guacamole login screen and have the option
+to log in with traditional credentials _or_ with CAS, ensure the CAS extension
+does not have priority:
+
+```
+extension-priority: *, cas
+```
+
 (completing-cas-install)=
 
 ### Completing the installation

diff --git a/src/conf.py b/src/conf.py
@@ -52,6 +52,10 @@
 
 templates_path = [ '_templates' ]
 
+# Do not parse files within include/ unless they are explicitly included with
+# the "include" directive
+exclude_patterns = [ 'include/**' ]
+
 # Do not highlight source unless a Pygments lexer name is explicitly provided
 highlight_language = 'none'
 

diff --git a/src/configuring-guacamole.md b/src/configuring-guacamole.md
@@ -149,6 +149,40 @@ that are always available for use:
   `guacd-hostname` property would be transformed to `GUACD_HOSTNAME` when
   searching the environment.
 
+`extension-priority`
+: A comma-separated list of the namespaces of all extensions that should be
+  loaded in a specific order. The special value `*` can be used in lieu of a
+  namespace to represent all extensions that are not listed. All extensions
+  explicitly listed will be sorted in the order given, while all extensions
+  not explicitly listed will be sorted by their filenames.
+
+  For example, to ensure support for SAML is loaded _first_:
+
+  ```
+  extension-priority: saml
+  ```
+
+  Or to ensure support for SAML is loaded _last_:
+
+  ```
+  extension-priority: *, saml
+  ```
+
+  If unsure which namespaces apply or the order that your extensions are
+  loaded, check the Guacamole logs. The namespaces and load order of all
+  installed extensions are logged by Guacamole during startup:
+
+  ```
+  ...
+  23:32:06.467 [main] INFO  o.a.g.extension.ExtensionModule - Multiple extensions are installed and will be loaded in order of decreasing priority:
+  23:32:06.468 [main] INFO  o.a.g.extension.ExtensionModule -  - [postgresql] "PostgreSQL Authentication" (/etc/guacamole/extensions/guacamole-auth-jdbc-postgresql-1.4.0.jar)
+  23:32:06.468 [main] INFO  o.a.g.extension.ExtensionModule -  - [ldap] "LDAP Authentication" (/etc/guacamole/extensions/guacamole-auth-ldap-1.4.0.jar)
+  23:32:06.468 [main] INFO  o.a.g.extension.ExtensionModule -  - [openid] "OpenID Authentication Extension" (/etc/guacamole/extensions/guacamole-auth-sso-openid-1.4.0.jar)
+  23:32:06.468 [main] INFO  o.a.g.extension.ExtensionModule -  - [saml] "SAML Authentication Extension" (/etc/guacamole/extensions/guacamole-auth-sso-saml-1.4.0.jar)
+  23:32:06.468 [main] INFO  o.a.g.extension.ExtensionModule - To change this order, set the "extension-priority" property or rename the extension files. The default priority of extensions is dictated by the sort order of their filenames.
+  ...
+  ```
+
 `guacd-hostname`
 : The host the Guacamole proxy daemon (guacd) is listening on. If omitted,
   Guacamole will assume guacd is listening on localhost.
@@ -1098,6 +1132,19 @@ connection, users will be able to upload and download files as described in
   leveraging the standard "`AUDIO_INPUT`" channel of RDP. By default, audio
   input support within RDP is disabled.
 
+`enable-touch`
+: If set to "true", support for multi-touch events will be enabled, leveraging
+  the standard "`RDPEI`" channel of RDP. By default, direct RDP support for
+  multi-touch events is disabled.
+
+  Enabling support for multi-touch allows touch interaction with applications
+  inside the RDP session, however the touch gestures available will depend on
+  the level of touch support of those applications and the OS.
+
+  If multi-touch support is not enabled, pointer-type interaction with
+  applications inside the RDP session will be limited to mouse or emulated
+  mouse events.
+
 `enable-printing`
 : Printing is disabled by default, but with printing enabled, RDP users can
   print to a virtual printer that sends a PDF containing the document

diff --git a/src/include/sso-download.md b/src/include/sso-download.md
@@ -0,0 +1,15 @@
+Guacamole's SSO extensions are available separately from the main
+`guacamole.war`. The link for this and all other officially-supported and
+compatible extensions for a particular version of Guacamole are provided on the
+release notes for that version. You can find the release notes for current
+versions of Guacamole here: <http://guacamole.apache.org/releases/>.
+
+The SSO extensions are packaged together in a `.tar.gz` file containing one
+extension for each supported SSO method:
+
+| SSO Method                    | Extension                                    |
+| ----------------------------- | -------------------------------------------- |
+| [CAS](cas-auth)               | `cas/guacamole-auth-sso-cas-1.4.0.jar`       |
+| [OpenID Connect](openid-auth) | `openid/guacamole-auth-sso-openid-1.4.0.jar` |
+| [SAML](saml-auth)             | `saml/guacamole-auth-sso-saml-1.4.0.jar`     |
+
diff --git a/src/include/sso-login-behavior.md b/src/include/sso-login-behavior.md
@@ -0,0 +1,20 @@
+Guacamole loads authentication extensions in order of priority, and evaluates
+authentication attempts in this same order. This has implications for how the
+Guacamole login process behaves when an SSO extension is present:
+
+If the SSO extension has priority:
+: Users that are not yet authenticated
+  will be immediately redirected to the configured identity provider. They will
+  not see a Guacamole login screen.
+
+If a non-SSO extension has priority:
+: Users that are not yet authenticated
+  will be presented with a Guacamole login screen. Additionally, links to the
+  configured identity provider(s) will be available for users that wish to log
+  in using SSO.
+
+The default priority of extensions is dictated by their filenames, with
+extensions that sort earlier alphabetically having higher priority than others.
+This can be overridden [by setting the `extension-priority` property within
+`guacamole.properties`](initial-setup).
+
diff --git a/src/openid-auth.md b/src/openid-auth.md
@@ -21,16 +21,12 @@ user authentication.
 Downloading the OpenID Connect authentication extension
 -------------------------------------------------------
 
-The OpenID Connect authentication extension is available separately from the
-main `guacamole.war`. The link for this and all other officially-supported and
-compatible extensions for a particular version of Guacamole are provided on the
-release notes for that version. You can find the release notes for current
-versions of Guacamole here: <http://guacamole.apache.org/releases/>.
+```{include} include/sso-download.md
+```
 
-The OpenID Connect authentication extension is packaged as a `.tar.gz` file
-containing only the extension itself, `guacamole-auth-openid-1.4.0.jar`, which
-must ultimately be placed in
-`GUACAMOLE_HOME/extensions`.
+The extension for the desired SSO method, in this case
+`guacamole-auth-sso-openid-1.4.0.jar` from within the `openid/` subdirectory,
+must ultimately be placed in `GUACAMOLE_HOME/extensions`.
 
 (installing-openid-auth)=
 
@@ -47,7 +43,8 @@ To install the OpenID Connect authentication extension, you must:
 1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already
    exist.
 
-2. Copy `guacamole-auth-openid-1.4.0.jar` within `GUACAMOLE_HOME/extensions`.
+2. Copy `guacamole-auth-sso-openid-1.4.0.jar` within
+   `GUACAMOLE_HOME/extensions`.
 
 3. Configure Guacamole to use OpenID Connect authentication, as described
    below.
@@ -147,6 +144,33 @@ aspects of the conversation with the identity provider:
   OpenID request can result in successful authentication within Guacamole. By
   default, each generated nonce expires after 10 minutes.
 
+(openid-login)=
+
+### Controlling login behavior
+
+```{include} include/sso-login-behavior.md
+```
+
+#### Automatically redirecting all unauthenticated users
+
+To ensure users are redirected to the OpenID identity provider immediately
+(without a Guacamole login screen), ensure the OpenID extension has priority
+over all others:
+
+```
+extension-priority: openid
+```
+
+#### Presenting unauthenticated users with a login screen
+
+To ensure users are given a normal Guacamole login screen and have the option
+to log in with traditional credentials _or_ with OpenID, ensure the OpenID
+extension does not have priority:
+
+```
+extension-priority: *, openid
+```
+
 (completing-openid-install)=
 
 ### Completing the installation

diff --git a/src/saml-auth.md b/src/saml-auth.md
@@ -15,15 +15,12 @@ management.
 Downloading the SAML authentication extension
 ---------------------------------------------
 
-The SAML authentication extension is available separately from the main
-`guacamole.war`. The link for this and all other officially-supported and
-compatible extensions for a particular version of Guacamole are provided on the
-release notes for that version. You can find the release notes for current
-versions of Guacamole here: <http://guacamole.apache.org/releases/>.
+```{include} include/sso-download.md
+```
 
-The SAML authentication extension is packaged as a `.tar.gz` file containing
-only the extension itself, `guacamole-auth-saml-1.4.0.jar`, which must
-ultimately be placed in `GUACAMOLE_HOME/extensions`.
+The extension for the desired SSO method, in this case
+`guacamole-auth-sso-saml-1.4.0.jar` from within the `saml/` subdirectory,
+must ultimately be placed in `GUACAMOLE_HOME/extensions`.
 
 (installing-saml-auth)=
 
@@ -40,7 +37,7 @@ To install the SAML authentication extension, you must:
 1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already
    exist.
 
-2. Copy `guacamole-auth-saml-1.4.0.jar` within `GUACAMOLE_HOME/extensions`.
+2. Copy `guacamole-auth-sso-saml-1.4.0.jar` within `GUACAMOLE_HOME/extensions`.
 
 3. Configure Guacamole to use SAML authentication, as described below.
 
@@ -109,6 +106,31 @@ the scope of this document, and will vary widely based on the IdP in use.
   management within Guacamole Client, particularly when layered with other
   authentication modules. This property is optional, and defaults to "groups".
 
+### Controlling login behavior
+
+```{include} include/sso-login-behavior.md
+```
+
+#### Automatically redirecting all unauthenticated users
+
+To ensure users are redirected to the SAML identity provider immediately
+(without a Guacamole login screen), ensure the SAML extension has priority over
+all others:
+
+```
+extension-priority: saml
+```
+
+#### Presenting unauthenticated users with a login screen
+
+To ensure users are given a normal Guacamole login screen and have the option
+to log in with traditional credentials _or_ with SAML, ensure the SAML
+extension does not have priority:
+
+```
+extension-priority: *, saml
+```
+
 (completing-saml-install)=
 
 ### Completing the installation