Skip to content
Permalink
Browse files
Merge 1.4.0 changes back to master.
  • Loading branch information
necouchman committed Dec 12, 2021
2 parents d3898b8 + 21a9d2a commit 73829a6629bfa547f24419089461c4521d053296
Showing 7 changed files with 184 additions and 28 deletions.
@@ -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
@@ -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'

@@ -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
@@ -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` |

@@ -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).

@@ -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
@@ -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

0 comments on commit 73829a6

Please sign in to comment.