GUACAMOLE-374: Migrate TOTP documentation to combined native+Docker a…

…pproach.
apache · Oct 13, 2024 · 373a236 · 373a236
1 parent 82aa331
commit 373a236
Show file tree

Hide file tree

Showing 3 changed files with 153 additions and 148 deletions.
diff --git a/src/include/totp-bypass-enforce.properties.in b/src/include/totp-bypass-enforce.properties.in
@@ -0,0 +1,27 @@
+#
+# A comma-separated list of all IP addresses and/or subnets (in CIDR notation)
+# that SHOULD NOT be required to verify themselves using TOTP when
+# authenticating. All other hosts in this list will required to verify with
+# TOTP.
+#
+# **If both bypass and enforce lists are provided, the enforce list takes
+# priority and this property is effectively ignored.**
+#
+# This property is optional. By default, verification will be required for all
+# users regardless of their IP address (TOTP is not bypassed for any
+# addresses).
+#
+totp-bypass-hosts: 10.10.0.0/8, 10.11.0.2
+
+#
+# A comma-separated list of all IP addresses and/or subnets (in CIDR notation)
+# that SHOULD be required to verify themselves using TOTP when authenticating.
+# All other hosts will not be required to verify with TOTP.
+#
+# **If both bypass and enforce lists are provided, the enforce list takes
+# priority and the bypass list is effectively ignored.**
+#
+# This property is optional. By default, verification will be required for all
+# users regardless of their IP address (TOTP is enforced for all addresses).
+#
+totp-enforce-hosts: 10.12.0.0/8
diff --git a/src/include/totp.properties.in b/src/include/totp.properties.in
@@ -0,0 +1,23 @@
+#
+# The human-readable name of the entity issuing user accounts. If not
+# specified, "Apache Guacamole" will be used by default.
+#
+totp-issuer: Apache Guacamole
+
+#
+# The number of digits which should be included in each generated TOTP code.
+# Legal values are 6, 7, or 8. By default, 6-digit codes are generated.
+#
+totp-digits: 6
+
+#
+# The duration that each generated code should remain valid, in seconds. By
+# default, each code remains valid for 30 seconds.
+#
+totp-period: 30
+
+#
+# The hash algorithm that should be used to generate TOTP codes. Legal values
+# are "sha1", "sha256", and "sha512". By default, "sha1" is used.
+#
+totp-mode: sha1
diff --git a/src/totp-auth.md b/src/totp-auth.md
@@ -1,3 +1,9 @@
+---
+myst:
+  substitutions:
+    extMachineName: guacamole-auth-totp
+---
+
 TOTP two-factor authentication
 ==============================
 
@@ -8,12 +14,8 @@ enrollment](totp-prerequisites) are met. The TOTP authentication extension
 allows users to be additionally verified against a user-specific and secret key
 generated during [enrollment of their authentication device](totp-enrollment).
 
-:::{important}
-This chapter involves modifying the contents of `GUACAMOLE_HOME` - the
-Guacamole configuration directory. If you are unsure where `GUACAMOLE_HOME` is
-located on your system, please consult [](configuring-guacamole) before
-proceeding.
-:::
+```{include} include/warn-config-changes.md
+```
 
 (totp-prerequisites)=
 
@@ -120,169 +122,122 @@ disabled for any members of the group.
 
 (totp-downloading)=
 
-Downloading the TOTP extension
+Downloading and Installing the TOTP extension
+---------------------------------------------
+
+```{include} include/ext-download.md
+```
+
+(guac-totp-config)=
+
+Configuring Guacamole for TOTP
 ------------------------------
 
-The TOTP 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/>.
+With the exception of [the storage and permission requirements described
+above](totp-prerequisites), the TOTP extension should work out-of-the-box
+without any additional configuration. Defaults have been chosen for all
+configuration parameters such that the TOTP extension will be compatible with
+Google Authenticator and similar, popular TOTP implementations.
 
-The TOTP authentication extension is packaged as a `.tar.gz` file containing
-only the extension itself, `guacamole-auth-totp-1.6.0.jar`, which must
-ultimately be placed in `GUACAMOLE_HOME/extensions`.
+:::{warning}
+Some TOTP applications *assume these defaults* and *silently ignore any other
+values*. **Google Authenticator is such an application.** Be sure your
+authenticator application supports the values you intend to use before
+overriding the defaults.
+:::
 
-(installing-totp-auth)=
+```{eval-rst}
+.. tab:: Native Webapp (Tomcat)
 
-Installing TOTP authentication
-------------------------------
+   If your intended authentication application or device has different
+   requirements, or you wish to override the defaults, additional properties
+   may be specified within ``guacamole.properties``:
 
-Guacamole extensions are self-contained `.jar` files which are located within
-the `GUACAMOLE_HOME/extensions` directory. To install the TOTP authentication
-extension, you must:
+   .. include:: include/totp.properties.md
+      :parser: myst_parser.sphinx_
 
-1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already
-   exist.
+.. tab:: Container (Docker)
 
-2. Copy `guacamole-auth-totp-1.6.0.jar` within `GUACAMOLE_HOME/extensions`.
+   If deploying Guacamole using Docker Compose, you will need to add at least
+   one TOTP environment variable to the ``environment`` section of your
+   ``guacamole/guacamole`` container, such as the ``TOTP_ENABLED`` environment
+   variable:
 
-3. Configure Guacamole to use TOTP authentication, as described below.
+   .. code-block:: yaml
 
-:::{important}
-You will need to restart Guacamole by restarting your servlet container in
-order to complete the installation. Doing this will disconnect all active
-users, so be sure that it is safe to do so prior to attempting installation. If
-you do not configure the TOTP authentication properly, Guacamole will not start
-up again until the configuration is fixed.
-:::
+      TOTP_ENABLED: "true"
 
-(guac-totp-config)=
+   If instead deploying Guacamole by running ``docker run`` manually, this same
+   environment variable will need to be provided using the ``-e`` option. For
+   example:
 
-### Configuring Guacamole for TOTP
+   .. code-block:: console
 
-With the exception of [the storage and permission requirements described
-above](totp-prerequisites), the TOTP extension should work out-of-the-box
-without any additional configuration. Defaults have been chosen for all
-configuration parameters such that the TOTP extension will be compatible with
-Google Authenticator and similar, popular TOTP implementations.
+      $ docker run --name some-guacamole \
+          -e TOTP_ENABLED="true" \
+          -d -p 8080:8080 guacamole/guacamole
+
+   If your intended authentication application or device has different
+   requirements, or you wish to override the defaults, additional environment
+   variables may be set:
+
+   .. include:: include/totp.environment.md
+      :parser: myst_parser.sphinx_
+
+   You can also explicitly enable/disable use of TOTP support by setting the
+   ``TOTP_ENABLED`` environment variable to ``true`` or ``false``:
+
+   ``TOTP_ENABLED``
+      Explicitly enables or disables use of the TOTP extension. By default, the
+      TOTP extension will be installed only if at least one TOTP-related
+      environment variable is set.
+
+      If set to ``true``, the TOTP extension will be installed regardless of any
+      other environment variables. If set to ``false``, the TOTP extension will
+      NOT be installed, even if other TOTP-related environment variables have
+      been set.
+```
 
-If your intended authentication application or device has different
-requirements, or you wish to override the defaults, additional properties may
-be specified within `guacamole.properties`:
-
-`totp-issuer`
-: The human-readable name of the entity issuing user accounts. If not
-  specified, "Apache Guacamole" will be used by default.
-
-`totp-digits`
-: The number of digits which should be included in each generated TOTP code.
-  Legal values are 6, 7, or 8. By default, 6-digit codes are generated.
-
-`totp-period`
-: The duration that each generated code should remain valid, in seconds. By
-  default, each code remains valid for 30 seconds.
-
-`totp-mode`
-: The hash algorithm that should be used to generate TOTP codes. Legal values
-  are "sha1", "sha256", and "sha512". By default, "sha1" is used.
-
-`totp-bypass-hosts`
-: By default, when the TOTP module is enabled, TOTP-based MFA will be enforced
-  for all users, from all clients, that attempt to log in to Guacamole.
-  This property allows for the TOTP requirement to be bypassed for users logging
-  in from a specified set of hosts. This option can contain a comma-separated
-  list of IP addresses and/or subnets, in CIDR notation, for which TOTP
-  MFA should not be required. This may be useful in scenarios where a single
-  Guacamole instance is used by both users inside and outside a network
-  boundary such that the users inside the boundary (VPN or Firewall) have
-  already achieved a certain level of authentication and do not need the
-  second layer of security, whereas users outside that boundary still
-  require the additional authentication layer.
-
-  This property is optional, and there is no default value. If no value
-  is specified, the TOTP module will require that all users from all sources
-  complete the secondary authentication.
-
-`totp-enforce-hosts`
-: Similar to the `totp-bypass-hosts` option above, this option specifies
-  hosts for which the TOTP MFA must absolutely be enforced. This option
-  helps provide flexibility in environments where you know that untrusted
-  connections will be coming in from a certain IP address or subnet so
-  that you can enforce the secondary authentication for those sources.
-  This value is optional with no default value.
+### Bypass/Enforce TOTP for Specific Hosts
+
+By default, when the TOTP module is enabled, TOTP-based MFA will be enforced for
+all users that attempt to log in to Guacamole, regardless of where they are
+connecting from. Depending on your use case, it may be necessary to narrow this
+behavior and only enforce TOTP-based MFA for certain hosts and bypass it for
+others.
 
 :::{important}
-  There are two items that are important to note about the above options
-  for either bypassing or enforcing TOTP logins based on IP address. First,
-  it is important that Tomcat and any upstream proxies (Nginx, Apache, etc.)
-  be properly configured to present the client IP address that will be used
-  to determine "trusted" vs. "untrusted" clients. This means configuring
-  Tomcat and the upstream proxies in such a way as to correctly forward
-  the client IP address information through to Guacamole, as documented
-  in the chapter on [](reverse-proxy).
-
-  Second, it's important to understand the various behaviors of these
-  options as they interact with each other. There are four possible
-  scenarios:
-
-  1. Neither option is specified. In this case, the TOTP module
-     enforces secondary authentication for all clients.
-     This is, obviously, the most secure scenario.
-
-  2. You specify a list of IP addresses or subnets in the
-     `totp-bypass-hosts` property and do not specify any in the
-     `totp-enforce-hosts` property. In this scenario, TOTP will
-     only bypass enforcement of the second authentication
-     mechanism for users logging in from hosts that fall
-     in the provided list, and will enforce second factor
-     authentication for users from all other clients.
-
-  3. You do not specify any hosts or subnets in the
-     `totp-bypass-hosts` property, but you specify one or more
-     hosts or subnets in the `totp-enforce-hosts` property.
-     In this scenario, TOTP will ONLY enforce second factor
-     authentication for the hosts that fall into the list of
-     enforced hosts, and users from all other clients will
-     be able to log on without the second authentication
-     factor.
-
-  4. You specify values for both the bypass and the enforce
-     lists, in which case only hosts listed in the enforce
-     list will actually have second factor authentication
-     enforced, and the bypass list will essentially be
-     meangingless, as all other hosts will be bypassed.
-
-     The one item to note in this scenario is what happens
-     if there is an overlap between the bypass list and the
-     enforce list, where a host is either specified in both
-     lists or is specified in one list but falls into a CIDR
-     range specified in the other list. In these cases,
-     the enforce list will always take precendence over
-     the bypass list, and TOTP MFA will be enforced.
+If bypassing or enforcing TOTP only for specific hosts, **Tomcat and any
+upstream proxies (Nginx, Apache, etc.) MUST be properly configured to forward
+the client IP address**, as documented in [](reverse-proxy).
 :::
 
+```{eval-rst}
+.. tab:: Native Webapp (Tomcat)
 
-(completing-totp-install)=
+   TOTP-based MFA can be explicitly bypassed or enforced on a per-host basis by
+   providing the relevant, exhaustive list of addresses/networks using either
+   of the following properties:
 
-### Completing the installation
+   .. include:: include/totp-bypass-enforce.properties.md
+      :parser: myst_parser.sphinx_
 
-Guacamole will only reread `guacamole.properties` and load newly-installed
-extensions during startup, so your servlet container will need to be restarted
-before TOTP authentication will take effect.  Restart your servlet container
-and give the new authentication a try.
+.. tab:: Container (Docker)
 
-:::{important}
-You only need to restart your servlet container. *You do not need to restart
-guacd*.
+   TOTP-based MFA can be explicitly bypassed or enforced on a per-host basis by
+   providing the relevant, exhaustive list of addresses/networks using either
+   of the following environment variables:
 
-guacd is completely independent of the web application and does not deal with
-`guacamole.properties` or the authentication system in any way. Since you are
-already restarting the servlet container, restarting guacd as well technically
-won't hurt anything, but doing so is completely pointless.
-:::
+   .. include:: include/totp-bypass-enforce.environment.md
+      :parser: myst_parser.sphinx_
+
+```
+
+(completing-totp-install)=
+
+Completing the installation
+---------------------------
+
+```{include} include/ext-completing.md
+```
 
-If Guacamole does not come back online after restarting your servlet container,
-check the logs. Problems in the configuration of the TOTP extension may prevent
-Guacamole from starting up, and any such errors will be recorded in the logs of
-your servlet container.