GUACAMOLE-374: Migrate HTTP header auth documentation to combined nat…

…ive+Docker approach.

src/header-auth.md

@@ -1,3 +1,9 @@
+---
+myst:
+  substitutions:
+    extMachineName: guacamole-auth-header
+---
+
 HTTP header authentication
 ==========================
 
@@ -7,83 +13,97 @@ authenticated user. This authentication method must be layered on top of some
 other authentication extension, such as those available from the main project
 website, in order to provide access to actual connections.
 
-:::{important}
-All external requests must be properly sanitized if this extension is used. The
-chosen HTTP header must be stripped from untrusted requests, such that the
-authentication service is the only possible source of that header. *If such
-sanitization is not performed, it will be trivial for malicious users to add
-this header manually, and thus gain unrestricted access.*
+:::{danger}
+**All external requests must be properly sanitized if this extension is used.**
+The chosen HTTP header must be stripped from untrusted requests, such that the
+authentication service is the _only_ possible source of that header.
+
+**If such sanitization is not performed, it will be trivial for malicious users
+to add this header manually, and thus gain unrestricted access.**
 :::
 
+
+```{include} include/warn-config-changes.md
+```
+
 (header-downloading)=
 
-Downloading the HTTP header authentication extension
-----------------------------------------------------
+Downloading and installing the HTTP header authentication extension
+-------------------------------------------------------------------
 
-The HTTP header 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/ext-download.md
+```
 
-The HTTP header authentication extension is packaged as a `.tar.gz` file
-containing only the extension itself, `guacamole-auth-header-1.6.0.jar`, which
-must ultimately be placed in `GUACAMOLE_HOME/extensions`.
+(guac-header-config)=
 
-(installing-header-auth)=
+### Configuring Guacamole for HTTP header authentication
 
-Installing HTTP header authentication
--------------------------------------
+This extension has no required properties. So long as you are satisfied with
+the default values noted below, this extension requires no configuration beyond
+installation.
 
-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.*
+:::{list-table} Default HTTP header authentication configuration
+:stub-columns: 1
+* - HTTP header name
+  - `REMOTE_USER`
+* - Case-sensitive usernames
+  - [System-wide global default](global-case-sensitive-usernames)
+:::
 
-To install the HTTP header authentication extension, you must:
+```{eval-rst}
+.. tab:: Native Webapp (Tomcat)
 
-1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already
-   exist.
+   If you wish to override the defaults, additional properties may be specified
+   within ``guacamole.properties``:
 
-2. Copy `guacamole-auth-header-1.6.0.jar` within `GUACAMOLE_HOME/extensions`.
+   .. include:: include/http-auth.properties.md
+      :parser: myst_parser.sphinx_
 
-3. Configure Guacamole to use HTTP header authentication, as described below.
+.. tab:: Container (Docker)
 
-(guac-header-config)=
+   If deploying Guacamole using Docker Compose, you will need to add at least
+   one HTTP header authentication-related environment variable to the
+   ``environment`` section of your ``guacamole/guacamole`` container, such as
+   the ``HTTP_AUTH_ENABLED`` environment variable:
 
-### Configuring Guacamole for HTTP header authentication
+   .. code-block:: yaml
+
+      HTTP_AUTH_ENABLED: "true"
+
+   If instead deploying Guacamole by running ``docker run`` manually, this same
+   environment variable will need to be provided using the ``-e`` option. For
+   example:
+
+   .. code-block:: console
+
+      $ docker run --name some-guacamole \
+          -e HTTP_AUTH_ENABLED="true" \
+          -d -p 8080:8080 guacamole/guacamole
+
+   If you wish to override the defaults, additional environment variables may
+   be set:
+
+   .. include:: include/http-auth.environment.md
+      :parser: myst_parser.sphinx_
+
+   You can also explicitly enable/disable use brute-force authentication
+   detection by setting the ``HTTP_AUTH_ENABLED`` environment variable to ``true``
+   or ``false``:
+
+   ``HTTP_AUTH_ENABLED``
+      Explicitly enables or disables use of brute-force authentication
+      detection. By default, brute-force authentication detection is enabled.
 
-The HTTP header authentication extension provides only one configuration
-property, and it is optional. By default, the extension will pull the username
-of the authenticated user from the `REMOTE_USER` header, if present. The header
-module has a couple of options available to help configure it to suit your
-particular environment:
-If your
-authentication system uses a different HTTP header, you will need to override
-this by specifying the `http-auth-header` property within
-[`guacamole.properties`](initial-setup):
-
-`http-auth-header`
-: The HTTP header containing the username of the authenticated user.  This
-  property is optional. If not specified, `REMOTE_USER` will be used by
-  default. If your authentication system uses a different HTTP header you
-  can use this option to override it and specify the header for Guacamole
-  to expect.
-
-`http-auth-case-sensitive-usernames`
-: Whether or not the header module, specifically, should treat usernames as
-  case sensitive or not. This option defaults to the
-  [global default set for the entire Guacamole installation](global-case-sensitive-usernames),
-  but can be overridden for the header module, if desired.
+      If set to ``true``, the brute-force authentication detection extension
+      will be installed regardless of any other environment variables. If set
+      to ``false``, the brute-force authentication detection extension will NOT
+      be installed, regardless of any other environment variables.
+```
 
 (completing-header-install)=
 
 ### 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 HTTP header 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
+```
 

src/include/http-auth.properties.in

@@ -0,0 +1,20 @@
+#
+# The HTTP header containing the username of the authenticated user.
+#
+# This property is optional. If not specified, `REMOTE_USER` will be used by
+# default. If your authentication system uses a different HTTP header you can
+# use this option to override it and specify the header for Guacamole to
+# expect.
+#
+http-auth-header: REMOTE_USER
+
+#
+# Whether the HTTP header authentication module should treat usernames as case
+# sensitive.
+#
+# If not specified, this option defaults to the [global default set for the
+# entire Guacamole installation](global-case-sensitive-usernames). If the
+# global setting is also not specified, the default behavior for Guacmole is to
+# consider usernames to be case-sensitive.
+#
+http-auth-case-sensitive-usernames: false