From fa4032a44fed95075423c3ee49521e9763d09375 Mon Sep 17 00:00:00 2001 From: Michael Jumper Date: Sat, 2 Nov 2024 14:42:08 -0700 Subject: [PATCH] GUACAMOLE-374: Migrate CAS documentation to combined native+Docker approach. --- src/cas-auth.md | 180 ++++++++++++------------- src/include/cas-optional.properties.in | 58 ++++++++ src/include/cas.properties.in | 11 ++ 3 files changed, 158 insertions(+), 91 deletions(-) create mode 100644 src/include/cas-optional.properties.in create mode 100644 src/include/cas.properties.in diff --git a/src/cas-auth.md b/src/cas-auth.md index 84c7764..e30a9e0 100644 --- a/src/cas-auth.md +++ b/src/cas-auth.md @@ -1,3 +1,10 @@ +--- +myst: + substitutions: + extArchiveName: guacamole-auth-sso + extJarName: cas/guacamole-auth-sso-cas +--- + CAS Authentication ================== @@ -10,103 +17,96 @@ connection information, as it only provides user authentication. (cas-downloading)= -Downloading the CAS authentication extension +Downloading and installing the CAS authentication extension +----------------------------------------------------------- + +```{include} include/ext-download.md +``` + +Configuring Guacamole for CAS Authentication -------------------------------------------- -```{include} include/sso-download.md +Guacamole's CAS support requires specifying two properties that describe the +CAS authentication server and the Guacamole deployment. These properties are +*absolutely required in all cases*, as they dictate how Guacamole should +connect to the CAS and how CAS should redirect users back to Guacamole once +their identity has been confirmed: + + +```{eval-rst} +.. tab:: Native Webapp (Tomcat) + + If deploying Guacamole natively, you will need to add a section to your + ``guacamole.properties`` that looks like the following: + + .. literalinclude:: include/cas.example.properties + :language: ini + + The properties that must be set in all cases for any Guacamole installation + using CAS are: + + .. include:: include/cas.properties.md + :parser: myst_parser.sphinx_ + +.. tab:: Container (Docker) + + If deploying Guacamole using Docker Compose, you will need to add a set of + environment varibles to the ``environment`` section of your + ``guacamole/guacamole`` container that looks like the following + + .. literalinclude:: include/cas.example.yml + :language: yaml + + If instead deploying Guacamole by running ``docker run`` manually, these + same environment variables will need to be provided using the ``-e`` option. + For example: + + .. literalinclude:: include/cas.example.txt + :language: console + + The environment variables that must be set in all cases for any Docker-based + Guacamole installation using CAS are: + + .. include:: include/cas.environment.md + :parser: myst_parser.sphinx_ ``` -The extension for the desired SSO method, in this case -`guacamole-auth-sso-cas-1.6.0.jar` from within the `cas/` subdirectory, must -ultimately be placed in `GUACAMOLE_HOME/extensions`. +### Additional Configuration Options -(installing-cas-auth)= +```{eval-rst} +.. tab:: Native Webapp (Tomcat) -Installing CAS authentication ------------------------------ + 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: -Guacamole extensions are self-contained `.jar` files which are located within -the `GUACAMOLE_HOME/extensions` directory. *If you are unsure where -`GUACAMOLE_HOME` is located on your system, please consult -[](configuring-guacamole) before proceeding.* + .. include:: include/cas-optional.properties.md + :parser: myst_parser.sphinx_ -To install the CAS authentication extension, you must: +.. tab:: Container (Docker) -1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already - exist. + Additional optional environment variables 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: -2. Copy `guacamole-auth-sso-cas-1.6.0.jar` within `GUACAMOLE_HOME/extensions`. + .. include:: include/cas-optional.environment.md + :parser: myst_parser.sphinx_ -3. Configure Guacamole to use CAS authentication, as described below. + You can also explicitly enable/disable use of CAS support by setting the + ``CAS_ENABLED`` environment variable to ``true`` or ``false``: -(guac-cas-config)= + ``CAS_ENABLED`` + Explicitly enables or disables use of the CAS extension. By default, the + CAS extension will be installed only if at least one CAS-related + environment variable is set. -### Configuring Guacamole for CAS Authentication + If set to ``true``, the CAS extension will be installed regardless of any + other environment variables. If set to ``false``, the CAS extension will + NOT be installed, even if other CAS-related environment variables have + been set. +``` -Guacamole's CAS support requires specifying two properties that describe the -CAS authentication server and the Guacamole deployment. These properties are -*absolutely required in all cases*, as they dictate how Guacamole should -connect to the CAS and how CAS should redirect users back to Guacamole once -their identity has been confirmed: -`cas-authorization-endpoint` -: The URL of the CAS authentication server. This should be the full path to the - base of the CAS installation. - -`cas-redirect-uri` -: 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-related data is -processed, including whether [CAS ClearPass](cas-clearpass) should be used and -how user group memberships should be derived: - -`cas-clearpass-key` -: If using CAS ClearPass to pass the SSO password to Guacamole, this parameter - specifies the private key file to use to decrypt the password. See [the section - on ClearPass](cas-clearpass) below. - -`cas-group-attribute` -: The CAS attribute that determines group membership, typically "memberOf". - This parameter is only required if using CAS to define user group memberships. - If omitted, groups aren't retrieved from CAS, and all other group-related - properties for CAS are ignored. - -`cas-group-format` -: The format that CAS will use for its group names. Possible values are - `plain`, for groups that are simple text names, or `ldap`, for groups that are - represented as LDAP DNs. If set to `ldap`, group names are always determined - from the last (leftmost) attribute of the DN. If omitted, `plain` is used by - default. - - This property has no effect if cas-group-attribute is not set. - -`cas-group-ldap-base-dn` -: The base DN to require for LDAP-formatted CAS groups. If specified, only CAS - groups beneath this DN will be included, and all other CAS groups will be - ignored. - - This property has no effect if cas-group-format is not `ldap`. - -`cas-group-ldap-attribute` -: The LDAP attribute to require for LDAP-formatted CAS groups. If specified, - only CAS groups that use this attribute for the name of the group will be - included. Note that LDAP group names are *always determined from the last - (leftmost) attribute of the DN*. Specifying this property will only have the - effect of ignoring any groups that do not use the specified attribute to - represent the group name. - - 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)= @@ -137,18 +137,16 @@ extension-priority: *, cas (completing-cas-install)= -### Completing the installation +Completing the installation +--------------------------- -Guacamole will only reread `guacamole.properties` and load newly-installed -extensions during startup, so your servlet container will need to be restarted -before CAS authentication can be used. *Doing this will disconnect all active -users, so be sure that it is safe to do so prior to attempting installation.* -When ready, restart your servlet container and give the new authentication a -try. +```{include} include/ext-completing.md +``` (cas-clearpass)= -### Using CAS ClearPass +Using CAS ClearPass +------------------- CAS has a function called ClearPass that can be used to cache the password used for SSO authentication and make that available to services at a later time. @@ -159,6 +157,6 @@ more information can be found on the Apereo CAS wiki at the following URL: Once you have CAS configured for credential caching, you need to configure the service with a keypair for passing the credential securely. The public key gets installed on the CAS server, while the private key gets configured with the -cas-clearpass-key property. The private key file needs to be in RSA PKCS8 +`cas-clearpass-key property`. The private key file needs to be in RSA PKCS8 format. diff --git a/src/include/cas-optional.properties.in b/src/include/cas-optional.properties.in new file mode 100644 index 0000000..99a5dcd --- /dev/null +++ b/src/include/cas-optional.properties.in @@ -0,0 +1,58 @@ +# +# If using CAS ClearPass to pass the SSO password to Guacamole, this parameter +# specifies the private key file to use to decrypt the password. See [the section +# on ClearPass](cas-clearpass) below. +# +cas-clearpass-key: /path/to/private-key.pem + +# +# The CAS attribute that determines group membership, typically "memberOf". +# This parameter is only required if using CAS to define user group memberships. +# If omitted, groups aren't retrieved from CAS, and all other group-related +# properties for CAS are ignored. +# +cas-group-attribute: memberOf + +# +# The format that CAS will use for its group names. Possible values are +# `plain`, for groups that are simple text names, or `ldap`, for groups that are +# represented as LDAP DNs. If set to `ldap`, group names are always determined +# from the last (leftmost) attribute of the DN. If omitted, `plain` is used by +# default. +# +# This property has no effect if cas-group-attribute is not set. +# +cas-group-format: plain + +# +# The base DN to require for LDAP-formatted CAS groups. If specified, only CAS +# groups beneath this DN will be included, and all other CAS groups will be +# ignored. +# +# This property has no effect if cas-group-format is not `ldap`. +# +cas-group-ldap-base-dn: ou=groups,dn=example,dn=net + +# +# The LDAP attribute to require for LDAP-formatted CAS groups. If specified, +# only CAS groups that use this attribute for the name of the group will be +# included. Note that LDAP group names are *always determined from the last +# (leftmost) attribute of the DN*. Specifying this property will only have the +# effect of ignoring any groups that do not use the specified attribute to +# represent the group name. +# +# This property has no effect if cas-group-format is not `ldap`. +# +cas-group-ldap-attribute: cn + +# +# "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-case-sensitive-usernames: false diff --git a/src/include/cas.properties.in b/src/include/cas.properties.in new file mode 100644 index 0000000..3754c74 --- /dev/null +++ b/src/include/cas.properties.in @@ -0,0 +1,11 @@ +# +# The URL of the CAS authentication server. This should be the full path to the +# base of the CAS installation. +# +cas-authorization-endpoint: https://cas.example.net + +# +# The URI to redirect back to upon successful authentication. Normally this +# will be the full URL of your Guacamole installation. +# +cas-redirect-uri: https://guac.example.net