Skip to content
Permalink
Browse files
GUACAMOLE-1364: Merge document SSO extension structure and behavior.
  • Loading branch information
necouchman committed Dec 12, 2021
2 parents f536ca7 + a77ea28 commit 21a9d2ac5773b17a38b5c714c4a4d552a6df705e
Showing 6 changed files with 137 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'

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

Please sign in to comment.