From 6f60c76b508bc2c67a516785b28b1cb91e085dce Mon Sep 17 00:00:00 2001 From: Michael Jumper Date: Thu, 17 Oct 2024 15:06:28 -0700 Subject: [PATCH] GUACAMOLE-374: Migrate JSON auth to combined native+Docker approach. --- src/include/json-optional.properties.in | 23 ++++ src/include/json.properties.in | 16 +++ src/json-auth.md | 136 +++++++++++++++--------- 3 files changed, 123 insertions(+), 52 deletions(-) create mode 100644 src/include/json-optional.properties.in create mode 100644 src/include/json.properties.in diff --git a/src/include/json-optional.properties.in b/src/include/json-optional.properties.in new file mode 100644 index 0000000..bea3cce --- /dev/null +++ b/src/include/json-optional.properties.in @@ -0,0 +1,23 @@ +# +# A comma-separated list of IP addresses or subnets (in CIDR notation) that +# should be allowed to authenticate using encrypted JSON authentication. If +# set, _only_ machines with IP addresses that match the addresses/subnets in +# this list will be allowed to authenticate in this way. All other attempts to +# authenticate with encrypted JSON authentication will fail, regardless of +# whether the JSON is correctly signed and encrypted. +# +# By default, no restriction is placed on which machines may attempt to use +# encrypted JSON authentication. +# +json-trusted-networks: 10.10.0.0/8, 10.11.0.2 + +# +# Whether the encrypted JSON 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. +# +json-case-sensitive-usernames: false diff --git a/src/include/json.properties.in b/src/include/json.properties.in new file mode 100644 index 0000000..d8edd4f --- /dev/null +++ b/src/include/json.properties.in @@ -0,0 +1,16 @@ +# +# The 128-bit value to use to decrypt and verify the signatures of received +# JSON data. This value must be expressed as a 32-digit hexadecimal value. +# +# Any 32-digit hexadecimal value will suffice as long as it is random enough to +# be impractical for a malicious user to guess. An easy way to generate such a +# key is to echo a secure passphrase through the `md5sum` utility. This is the +# technique OpenSSL itself uses to generate 128-bit keys from passphrases. For +# example: +# +# ```console +# $ echo -n "ThisIsATest" | md5sum +# 4c0b569e4c96df157eee1b65dd0e4d41 +# ``` +# +json-secret-key: 4c0b569e4c96df157eee1b65dd0e4d41 diff --git a/src/json-auth.md b/src/json-auth.md index b5ea5f6..d1a69cf 100644 --- a/src/json-auth.md +++ b/src/json-auth.md @@ -1,3 +1,9 @@ +--- +myst: + substitutions: + extMachineName: guacamole-auth-json +--- + Encrypted JSON authentication ============================= @@ -8,81 +14,107 @@ contains [all information describing the user being authenticated](#json-format) as well as any connections they have access to, and is accepted only if the configured secret key was used to sign and encrypt the data. +```{include} include/warn-config-changes.md +``` + (json-downloading)= -Downloading the JSON authentication extension ---------------------------------------------- +Downloading and installing the JSON authentication extension +------------------------------------------------------------ -The JSON 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: . +```{include} include/ext-download.md +``` -The JSON authentication extension is packaged as a `.tar.gz` file containing -only the extension itself, `guacamole-auth-json-1.6.0.jar`, which must -ultimately be placed in `GUACAMOLE_HOME/extensions`. +(json-config)= -(installing-json-auth)= +Configuring Guacamole to accept encrypted JSON +---------------------------------------------- -Installing JSON authentication ------------------------------- +To verify and decrypt the received signed and encrypted JSON, a secret key must +be generated which will be shared by both the Guacamole server and systems that +will generate the JSON data. As guacamole-auth-json uses 128-bit AES, this key +must be 128 bits. -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.* +```{eval-rst} +.. tab:: Native Webapp (Tomcat) -To install the JSON authentication extension, you must: + If deploying Guacamole natively, you will need to add a section to your + ``guacamole.properties`` that looks like the following: -1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already - exist. + .. literalinclude:: include/json.example.properties + :language: ini -2. Copy `guacamole-auth-json-1.6.0.jar` within `GUACAMOLE_HOME/extensions`. + There is only a single property that must be set in all cases for any + Guacamole installation using the encrypted JSON authentication extension: -3. Configure Guacamole to use JSON authentication, as described below. + .. include:: include/json.properties.md + :parser: myst_parser.sphinx_ -(json-config)= +.. tab:: Container (Docker) -### Configuring Guacamole to accept encrypted JSON + 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 -To verify and decrypt the received signed and encrypted JSON, a secret key must -be generated which will be shared by both the Guacamole server and systems that -will generate the JSON data. As guacamole-auth-json uses 128-bit AES, this key -must be 128 bits. + .. literalinclude:: include/json.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/json.example.txt + :language: console + + There is only a single environment variable that must be set in all cases + for any Guacamole installation using the encrypted JSON authentication + extension: + + .. include:: include/json.environment.md + :parser: myst_parser.sphinx_ +``` + +### Additional Configuration Options + +```{eval-rst} +.. tab:: Native Webapp (Tomcat) + + The following additional, optional properties may be set as desired to + tailor the behavior of the encrypted JSON authentication: + + .. include:: include/json-optional.properties.md + :parser: myst_parser.sphinx_ + +.. tab:: Container (Docker) -An easy way of generating such a key is to echo a passphrase through the -"md5sum" utility. This is the technique OpenSSL itself uses to generate 128-bit -keys from passphrases. For example: + The following additional, optional environment variables may be set as + desired to tailor the encrypted JSON authentication: - $ echo -n "ThisIsATest" | md5sum - 4c0b569e4c96df157eee1b65dd0e4d41 - + .. include:: include/json-optional.environment.md + :parser: myst_parser.sphinx_ -The generated key must then be saved within [`guacamole.properties`](initial-setup) -as the full 32-digit hex value using the `json-secret-key` property: + You can also explicitly enable/disable use of encrypted JSON authentication + by setting the ``JSON_ENABLED`` environment variable to ``true`` or + ``false``: - json-secret-key: 4c0b569e4c96df157eee1b65dd0e4d41 + ``JSON_ENABLED`` + Explicitly enables or disables use of the encrypted JSON authentication + extension. By default, the encrypted JSON extension will be installed + only if at least one related environment variable is set. -The JSON module also supports the `json-case-sensitive-usernames` property, -which, if set to "true", will tell the JSON module to treat usernames processed -through the module in a case-sensitive manner. If set to "false", the module -will not consider case differences when comparing usernames. It's important -to note that the underlying system sending the JSON data may or may not treat -usernames as case-sensitive, so the configuration of this property should -match the expected behavior of the authentication system. The default for this -value is inherited from the -[global Guacamole case-sensitivity setting](global-case-sensitive-usernames). + If set to ``true``, the encrypted JSON extension will be installed + regardless of any other environment variables. If set to ``false``, the + encrypted JSON extension will NOT be installed, even if other related + environment variables have been set. +``` (completing-json-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 JSON 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 +``` (json-format)=