GUACAMOLE-374: Migrate CAS documentation to combined native+Docker ap…

…proach.
apache · Nov 2, 2024 · fa4032a · fa4032a
1 parent f85f3d4
commit fa4032a
Show file tree

Hide file tree

Showing 3 changed files with 158 additions and 91 deletions.
diff --git 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
@@ -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
@@ -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