diff --git a/.gitignore b/.gitignore index d304cc9..f6272e5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,10 @@ /build *~ __pycache__ + +# Documentation generated using generate-conf-docs.pl +*.properties.md +*.environment.md +*.example.properties +*.example.yml +*.example.txt diff --git a/Dockerfile b/Dockerfile index dac3e57..a74f874 100644 --- a/Dockerfile +++ b/Dockerfile @@ -27,7 +27,7 @@ ARG HTTPD_VERSION=2.4 # Perform the build itself using Python+Sphinx FROM sphinxdoc/sphinx AS builder -RUN pip3 install sphinx-rtd-theme sphinx-inline-tabs myst-parser +RUN pip3 install sphinx-rtd-theme sphinx-inline-tabs sphinx-copybutton myst-parser # Set the working directory for the remainder of the build process WORKDIR /manual diff --git a/Makefile b/Makefile index a7607d9..7dc3026 100644 --- a/Makefile +++ b/Makefile @@ -19,6 +19,19 @@ .PHONY: all clean html +# All files which the build depends on +MD_FILES=$(shell find "./src" -name "*.md") +RST_FILES=$(shell find "./src" -name "*.rst") +PNG_FILES=$(shell find "./src" -name "*.png") +PROPERTIES_TEMPLATES=$(shell find "./src" -name "*.properties.in") + +# Files that are automatically generated by the build +GENERATED_FILES += $(PROPERTIES_TEMPLATES:.properties.in=.properties.md) +GENERATED_FILES += $(PROPERTIES_TEMPLATES:.properties.in=.environment.md) +GENERATED_FILES += $(PROPERTIES_TEMPLATES:.properties.in=.example.properties) +GENERATED_FILES += $(PROPERTIES_TEMPLATES:.properties.in=.example.yml) +GENERATED_FILES += $(PROPERTIES_TEMPLATES:.properties.in=.example.txt) + # # Build entire manual # @@ -30,12 +43,26 @@ all: html # clean: - $(RM) -R build/ + $(RM) -R build/ $(GENERATED_FILES) -# All files which the build depends on -MD_FILES=$(shell find "./src" -name "*.md") -RST_FILES=$(shell find "./src" -name "*.rst") -PNG_FILES=$(shell find "./src" -name "*.png") +# +# Automatic generation of property documentation/examples +# + +%.properties.md: %.properties.in + ./generate-conf-docs.pl --mode=property-docs $< > $@ + +%.environment.md: %.properties.in + ./generate-conf-docs.pl --mode=environment-docs $< > $@ + +%.example.properties: %.properties.in + ./generate-conf-docs.pl --mode=property-example $< > $@ + +%.example.yml: %.properties.in + ./generate-conf-docs.pl --mode=docker-compose-example $< > $@ + +%.example.txt: %.properties.in + ./generate-conf-docs.pl --mode=docker-command-example $< > $@ # # HTML manual build @@ -43,6 +70,6 @@ PNG_FILES=$(shell find "./src" -name "*.png") html: build/html/index.html -build/html/index.html: $(PNG_FILES) $(RST_FILES) $(MD_FILES) +build/html/index.html: $(PNG_FILES) $(RST_FILES) $(MD_FILES) $(GENERATED_FILES) sphinx-build -b html -d build/doctrees src/ build/html diff --git a/README.md b/README.md index 7a3aa95..b9ca299 100644 --- a/README.md +++ b/README.md @@ -53,19 +53,20 @@ Building the Guacamole manual from source requires: * [sphinx-rtd-theme](https://pypi.org/project/sphinx-rtd-theme/) (the ReadTheDocs theme for Sphinx), * [sphinx-inline-tabs](https://pypi.org/project/sphinx-inline-tabs/) + * [sphinx-copybutton](https://pypi.org/project/sphinx-copybutton/) * [myst-parser](https://pypi.org/project/myst-parser/) The required Python packages can be installed using the "pip" package manager: ```console -$ pip install sphinx sphinx-rtd-theme sphinx-inline-tabs myst-parser +$ pip install sphinx sphinx-rtd-theme sphinx-inline-tabs sphinx-copybutton myst-parser ``` On some systems, the Python 3 version of "pip" may instead be named "pip3", to maintain compatability with users and scripts that expect Python 2: ```console -$ pip3 install sphinx sphinx-rtd-theme sphinx-inline-tabs myst-parser +$ pip3 install sphinx sphinx-rtd-theme sphinx-inline-tabs sphinx-copybutton myst-parser ``` Building the manual diff --git a/generate-conf-docs.pl b/generate-conf-docs.pl new file mode 100755 index 0000000..4194a3d --- /dev/null +++ b/generate-conf-docs.pl @@ -0,0 +1,182 @@ +#!/usr/bin/perl +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +# +# generate-conf-docs.pl - Parses example guacamole.properties snippets to +# produce documentation for both the properties used in the snippet and their +# corresponding Docker environment variables. Example guacamole.properties +# excerpts and docker-compose.yml excerpts are also produced. +# +# USAGE: ./generate-conf-docs.pl --mode=MODE [FILES...] +# +# Parses each of the given files, writing all output to STDOUT. The provided +# MODE dictates the format of that output. Valid modes are: +# +# "property-docs" - Generate a Markdown definition list (MyST format) that +# lists each property, where the property name is the term and the content of +# all comments above that property are the definition. Markdown formatting +# within the comment will be preserved. If a property is commented out, that +# property will still be included in the documentation. +# +# "property-example" - Generate an example guacamole.properties snippet that +# lists each individual property, including the value provided for that +# property in the input file. Documentation from comments related to the +# property are omitted from the output. If a property is commented out, that +# property will still be included in the output snippet in commented-out +# form. +# +# "environment-docs" - Generate a Markdown definition list (MyST format) that +# lists each property, where the property's corresponding environment +# variable name is the term and the content of all comments above that +# property are the definition. Markdown formatting within the comment will be +# preserved. If a property is commented out, the environment variable for +# that property will still be included in the documentation. +# +# "docker-compose-example" - Generate an example docker-compose.yml snippet +# that lists the environment variables that correspond to each individual +# property, including the value provided for that property in the input file. +# Documentation from comments related to the property are omitted from the +# output. If a property is commented out, the environment variable +# corresponding to that property will still be included in the output snippet +# in commented-out form. +# +# "docker-command-example" - Generate an example "docker run" command that +# shows "-e" options for each of the environment variables that correspond to +# each individual property, including the value provided for that property in +# the input file. Documentation from comments related to the property are +# omitted from the output. If a property is commented out, the environment +# variable corresponding to that property will be omitted from the output +# snippet. +# + +use strict; +use warnings; + +use Getopt::Long; + +# +# Mapping of output modes to functions that print using the format that output +# mode requires. Each function accepts up to 4 arguments, in order: +# +# 1. The name of the property. +# 2. The Markdown-formatted documentation associated with that property +# (extracted from comments above the property). +# 3. The value assigned to that property in the input file. +# 4. An arbitrary value that is truthy if the line containing the property as +# commented out (falsy otherwise). +# +my %output_handlers = ( + + 'property-docs' => sub { + print "`$_[0]`\n$_[1]\n"; + }, + + 'property-example' => sub { + !$_[3] or print "#"; + print "$_[0]: $_[2]\n"; + }, + + 'environment-docs' => sub { + $_[0] =~ tr/a-z-/A-Z_/; + print "`$_[0]`\n$_[1]\n"; + }, + + 'docker-compose-example' => sub { + !$_[3] or print "#"; + $_[0] =~ tr/a-z-/A-Z_/; + $_[2] =~ s/'/''/g; + print "$_[0]: '$_[2]'\n"; + }, + + 'docker-command-example' => sub { + $_[0] =~ tr/a-z-/A-Z_/; + $_[2] =~ s/[\$`"\\]/\\&/g; + print " -e $_[0]=\"$_[2]\" \\\n"; + } + +); + +# +# Mapping of output modes to the strings that should be printed at the +# beginning of all output, if any. +# +my %headers = ( + 'docker-command-example' => "\$ docker run --name some-guacamole \\\n" +); + +# +# Mapping of output modes to the strings that should be printed at the +# end of all output, if any. +# +my %footers = ( + 'docker-command-example' => " -d -p 8080:8080 guacamole/guacamole\n" +); + +# Default to outputting property documentation +my $output_mode = "property-docs"; + +# Parse all options (currently there is only one: --mode) +GetOptions( 'mode=s' => \$output_mode ) or die; + +# Verify the provided mode is valid, selecting the appropriate output function +# for the chosen mode +my $print_docs = $output_handlers{$output_mode} or die "Invalid output mode: $output_mode\n"; + +my $new_paragraph = 0; +my $property_docs = ""; + +print $headers{$output_mode} if defined $headers{$output_mode}; +while (<>) { + + # Gradually accumulate documentation from comments that precede a + # property/value pair + if ((my $content) = m/^# (\S.*)$/) { + + if ($property_docs ne "") { + if ($new_paragraph) { + $property_docs .= "\n"; + } + $property_docs .= " "; + } + else { + $property_docs .= ":"; + } + + $property_docs .= " $content\n"; + $new_paragraph = 0; + + } + + # Comments that are empty or consist of nothing but whitespace indicate a + # new paragraph + elsif (m/^#\s*$/) { + $new_paragraph = 1; + } + + # Once a property/value pair is finally encountered, output the + # documentation accumulated so far using the selected output function + elsif ((my $comment_char, my $property, my $property_value) = m/^(#)?(\S+):\s+(.*)/) { + &$print_docs($property, $property_docs, $property_value, defined($comment_char)); + $property_docs = ""; + } + +} +print $footers{$output_mode} if defined $footers{$output_mode}; + diff --git a/src/adhoc-connections.md b/src/adhoc-connections.md index f1aa957..7bafbc6 100644 --- a/src/adhoc-connections.md +++ b/src/adhoc-connections.md @@ -1,3 +1,10 @@ +--- +myst: + substitutions: + extArchiveName: guacamole-auth-quickconnect + extJarName: guacamole-auth-quickconnect +--- + Ad-hoc Connections ================== @@ -32,71 +39,82 @@ well-understood by administrators prior to implementing it: sensitive system files by allowing access to them. ::: +```{include} include/warn-config-changes.md +``` + (quickconnect-downloading)= -Downloading the quickconnect extension --------------------------------------- +Downloading and installing the quickconnect extension +----------------------------------------------------- -The quickconnect 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 in the -release notes for that version. You can find the release notes for current -versions of Guacamole here: . +```{include} include/ext-download.md +``` -The quickconnect extension is packaged as a `.tar.gz` file containing only the -extension itself, `guacamole-auth-quickconnect-1.6.0.jar`, which must -ultimately be placed in `GUACAMOLE_HOME/extensions`. +(guac-quickconnect-config)= -(installing-quickconnect)= +Configuring Guacamole for the quickconnect extension +---------------------------------------------------- -Installing the quickconnect extension -------------------------------------- +```{eval-rst} +.. tab:: Native Webapp (Tomcat) -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.* + The quickconnect extension has two configuration properties that allow for + controlling what connection parameters can be used in the URIs that are + opened with the quickconnect extension: -To install the extension, you must: + .. include:: include/quickconnect.properties.md + :parser: myst_parser.sphinx_ -1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already - exist. +.. tab:: Container (Docker) -2. Place the `guacamole-auth-quickconnect-1.6.0.jar` file in the - `GUACAMOLE_HOME/extensions` directory. + If deploying Guacamole using Docker Compose, you will need to add at least + one quickconnect-related environment variable to the ``environment`` section + of your ``guacamole/guacamole`` container, such as the ``QUICKCONNECT_ENABLED`` + environment variable: -(guac-quickconnect-config)= + .. code-block:: yaml + + QUICKCONNECT_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 QUICKCONNECT_ENABLED="true" \ + -d -p 8080:8080 guacamole/guacamole + + The quickconnect extension has two environment variables that allow for + controlling what connection parameters can be used in the URIs that are + opened with the quickconnect extension: -### Configuring Guacamole for the quickconnect extension + .. include:: include/quickconnect.environment.md + :parser: myst_parser.sphinx_ -The quickconnect extension has two configuration properties that allow for -controlling what connection parameters can be used in the URIs that are opened -with the quickconnect extension: + You can also explicitly enable/disable use of the quickconnect extension by + setting the ``QUICKCONNECT_ENABLED`` environment variable to ``true`` or + ``false``: -`quickconnect-allowed-parameters` -: An optional list of parameters that are allowed to be used by connections - that are created and accessed via the quickconnect extension. If this - property is present, only parameters in this list will be allowed. If this - property is absent, any/all parameters will be allowed unless explicitly - denied using the `quickconnect-denied-parameters` property. + ``QUICKCONNECT_ENABLED`` + Explicitly enables or disables use of the quickconnect extension. By + default, the quickconnect extension will be installed only if at least + one quickconnect-related environment variable is set. -`quickconnect-denied-parameters` -: An optional list of parameters that are explicitly denied from being used by - connections created and accessed via the quickconnect extension. If this - property is present, any parameters in this list will be removed from the - connection configuration when it is created, *even if those parameter are - listed above in the `quickconnect-allowed-parameters` property.* If this - property is not present, no connection parameters will be explicitly denied. + If set to ``true``, the quickconnect extension will be installed + regardless of any other environment variables. If set to ``false``, the + quickconnect extension will NOT be installed, even if other + quickconnect-related environment variables have been set. +``` (completing-quickconnect-install)= -### Completing the installation +Completing the installation +--------------------------- -Guacamole will only load newly-installed extensions during startup, so your -servlet container will need to be restarted before the quickconnect extension -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 extension a try. +```{include} include/ext-completing.md +``` (using-quickconnect)= diff --git a/src/auth-ban.md b/src/auth-ban.md index c81a556..e5dbf0e 100644 --- a/src/auth-ban.md +++ b/src/auth-ban.md @@ -1,83 +1,82 @@ -Securing Guacamole against brute force attacks +--- +myst: + substitutions: + extArchiveName: guacamole-auth-ban + extJarName: guacamole-auth-ban +--- + +Securing Guacamole against brute-force attacks ============================================== Version 1.6.0 of Guacamole introduces an extension that allows you to detect -and block brute-force login attacks. The extension, `guacamole-auth-ban`, can -be installed alongside any of Guacamole's other extensions that provide user -authentication, and will track the IP address of failed authentication attempts -and, once the threshold of failed logins is reached, will block further logins -from that IP address for a given amount of time. +and block brute-force login attacks. When installed, the extension will track +the IP addresses of failed authentication attempts. Once the threshold of +failed logins is reached for a particular IP address, further logins from that +address will be temporarily banned: -:::{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. -::: +![](images/too-many-failed-logins.png) -Downloading the auth-ban extension ----------------------------------- -The guacamole-auth-ban 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/warn-config-changes.md +``` -The extension is packaged as a `.tar.gz` file containing only the extension -itself, `guacamole-auth-ban-1.6.0.jar`, which must ultimately be placed in -`GUACAMOLE_HOME/extensions`. +Downloading and installing brute-force authentication detection +--------------------------------------------------------------- -(installing-auth-ban)= +```{include} include/ext-download.md +``` -Installing the auth-ban extension ---------------------------------- +(auth-ban-config)= -Guacamole extensions are self-contained `.jar` files which are located within -the `GUACAMOLE_HOME/extensions` directory. To install the guacamole-auth-ban -extension, you must: +Configuring Guacamole for brute-force authentication detection +-------------------------------------------------------------- + +This extension has no required properties. So long as you are satisfied with +the default threshold and limits noted below, this extension requires no +configuration beyond installation. + +:::{list-table} Default brute-force authentication detection threshold and limits +:stub-columns: 1 +* - Maximum invalid attempts (authentication failures) + - 5 +* - Address ban duration + - 300 (5 minutes) +* - Maximum addresses tracked + - 10485670 +::: -1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already - exist. -2. Copy `guacamole-auth-ban-1.6.0.jar` within `GUACAMOLE_HOME/extensions`. +```{eval-rst} +.. tab:: Native Webapp (Tomcat) -3. [Configure the auth-ban extension thresholds, as described below](auth-ban-config), - if want parameters other than the defaults (also noted below). + If you wish to override the defaults, additional properties may be specified + within ``guacamole.properties``: -:::{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. -::: + .. include:: include/ban.properties.md + :parser: myst_parser.sphinx_ -(auth-ban-config)= - -### Configuring Guacamole for authentication failure protection +.. tab:: Container (Docker) -This extension has no required properties, and, so long as you are satisfied -with the default threshold noted below, requires no configuration beyond the -installation of the extension and reload of the web application. + **Brute-force authentication detection is enabled by default when using the + Docker image.** If you wish to override the defaults, additional environment + variables may be set: -If you wish to adjust the thresholds for how Guacamole handles protection -against brute force authentication attacks, the following properties are -available to you to configure the auth-ban extension: + .. include:: include/ban.environment.md + :parser: myst_parser.sphinx_ -`ban-max-invalid-attempts` -: The number of authentication failures ater which the extension will block - further logins from the client IP address. This property is optional and - the default is 5. + You can also explicitly enable/disable use of brute-force authentication + detection by setting the ``BAN_ENABLED`` environment variable to ``true`` or + ``false``: -`ban-address-duration` -: The length of time for which a client IP address will be denied logins - after the maximum authentication failures, in seconds. This property is - optional and has a default value of 300 seconds (five minutes). + ``BAN_ENABLED`` + Explicitly enables or disables use of brute-force authentication + detection. By default, brute-force authentication detection is enabled. -`ban-max-addresses` -: The maximum number of client IP addresses that the extension will track - in-memory before the oldest client IP is discarded in a Least-Recently - Used (LRU) fashion. This property is optional and has a default value - of 10485670 (1 million IP addresses). + 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. +``` :::{important} Because the extension tracks authentication failures based on the client @@ -90,19 +89,9 @@ Guacamole behind a proxy. (completing-auth-ban-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 installation of the auth-ban extension will take effect. +Completing the installation +--------------------------- -(using-auth-ban)= +```{include} include/ext-completing.md +``` -### Using the extension - -Once the extension is installed and the web application restarted, Guacamole -will immediately begin tracking login failures and blocking login attempts -from systems that reach the maximum failure threshold. Once an IP address is -blocked you'll see a message on the login page: - -![](images/too-many-failed-logins.png) diff --git a/src/auth-restrict.md b/src/auth-restrict.md index 15723c6..e20b852 100644 --- a/src/auth-restrict.md +++ b/src/auth-restrict.md @@ -1,3 +1,10 @@ +--- +myst: + substitutions: + extArchiveName: guacamole-auth-restrict + extJarName: guacamole-auth-restrict +--- + Enforcing Advanced Login and Connection Restrictions ==================================================== @@ -19,73 +26,62 @@ connections, and connection groups. Currently the only extension provided by the Guacamole project that is capable of doing this is the [JDBC authentication extension](jdbc-auth). -:::{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 +``` -Downloading the auth-restrict extension ---------------------------------------- +(installing-auth-restrict)= -The guacamole-auth-restrict 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/. +Downloading and installing auth-restrict extension +-------------------------------------------------- -The extension is packaged as a `.tar.gz` file containing only the extension -itself, `guacamole-auth-restrict-1.6.0.jar`, which must ultimately be placed -in `GUACAMOLE_HOME/extensions`. +```{include} include/ext-download.md +``` -(installing-auth-restrict)= +(auth-restrict-config)= -Installing the auth-restrict extension --------------------------------------- +### Configuring Guacamole for advanced restrictions -Guacamole extensions are self-contained `.jar` files which are located within -the `GUACAMOLE_HOME/extensions` directory. To install the -guacamole-auth-restrict extension, you must: +```{eval-rst} +.. tab:: Native Webapp (Tomcat) -1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already - exist. + There are no configuration options that need to be set within + ``guacamole.properties`` in order to use this extension. Simply placing the + extension within ``GUACAMOLE_HOME/extensions`` is sufficient to make use of + its functionality. -2. Copy `guacamole-auth-restrict-1.6.0.jar` within `GUACAMOLE_HOME/extensions`. +.. tab:: Container (Docker) -3. [As noted below](using-auth-restrict), apply additional restrictions to - users, user groups, connections, and/or connection groups. + If deploying Guacamole using Docker Compose, you will need to add the + ``RESTRICT_ENABLED`` environment variable to the ``environment`` section of + your ``guacamole/guacamole`` container, setting its value to ``"true"``: -:::{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. -::: + .. code-block:: yaml -(auth-restrict-config)= + RESTRICT_ENABLED: "true" -### Configuring Guacamole for advanced restrictions + If instead deploying Guacamole by running ``docker run`` manually, this same + environment variable will need to be provided using the ``-e`` option. For + example: -There are no guacamole.properties parameters that need to be configured -in order to begin using the auth-restrict extension. + .. code-block:: console -:::{important} -However, because the extension is capable of restricting access to logins and -connections based on the client's IP address, it is important to make sure -that Guacamole is receiving the correct IP address(es) for clients. This is -particularly noteworthy when Guacamole is behind a reverse proxy, as -documented in the [proxying Guacamole](reverse-proxy) manual page, but -administrators should validate any potential network component that may filter -or modify the IP address that Guacamole receives for client connections. -::: + $ docker run --name some-guacamole \ + -e RESTRICT_ENABLED="true" \ + -d -p 8080:8080 guacamole/guacamole + + There are no other configuration options required to make use of this + extension. +``` + +```{include} include/ext-client-ips.md +``` (completing-auth-restrict-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 installation of the auth-restrict extension will take effect. +```{include} include/ext-completing.md +``` (using-auth-restrict)= @@ -192,9 +188,9 @@ those hostnames is consistent. ::: As an example, suppose that you have a group of users that you'd like to -restrict logins such that they can only log in from a specific internal subnet -- let's say 192.168.123.0/24. You would simply put that subnet in the allowed -hosts box, and Guacamole would allow access for users to log in from IP +restrict logins such that they can only log in from a specific internal +subnet - let's say 192.168.123.0/24. You would simply put that subnet in the +allowed hosts box, and Guacamole would allow access for users to log in from IP addresses within that subnet, but block access from all other subnets: ![](images/auth-restrict-login-local-subnet.png) diff --git a/src/cas-auth.md b/src/cas-auth.md index 9b91c1c..1752b8c 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,95 +17,94 @@ connection information, as it only provides user authentication. (cas-downloading)= -Downloading the CAS authentication extension --------------------------------------------- +Downloading and installing the CAS authentication extension +----------------------------------------------------------- -```{include} include/sso-download.md +```{include} include/ext-download.md ``` -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`. +Configuring Guacamole for CAS Authentication +-------------------------------------------- -(installing-cas-auth)= +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: -Installing CAS authentication ------------------------------ -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 CAS 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/cas.example.properties + :language: ini -2. Copy `guacamole-auth-sso-cas-1.6.0.jar` within `GUACAMOLE_HOME/extensions`. + The properties that must be set in all cases for any Guacamole installation + using CAS are: -3. Configure Guacamole to use CAS authentication, as described below. + .. include:: include/cas.properties.md + :parser: myst_parser.sphinx_ -(guac-cas-config)= +.. tab:: Container (Docker) -### Configuring Guacamole for CAS Authentication + 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 -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: + .. literalinclude:: include/cas.example.yml + :language: yaml -`cas-authorization-endpoint` -: The URL of the CAS authentication server. This should be the full path to the - base of the CAS installation. + If instead deploying Guacamole by running ``docker run`` manually, these + same environment variables will need to be provided using the ``-e`` option. + For example: -`cas-redirect-uri` -: The URI to redirect back to upon successful authentication. Normally this - will be the full URL of your Guacamole installation. + .. literalinclude:: include/cas.example.txt + :language: console -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: + The environment variables that must be set in all cases for any Docker-based + Guacamole installation using CAS are: -`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. + .. include:: include/cas.environment.md + :parser: myst_parser.sphinx_ +``` -`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. +### Additional Configuration Options -`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. +```{eval-rst} +.. tab:: Native Webapp (Tomcat) - This property has no effect if cas-group-attribute is not set. + 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-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. + .. include:: include/cas-optional.properties.md + :parser: myst_parser.sphinx_ - This property has no effect if cas-group-format is not `ldap`. +.. tab:: Container (Docker) -`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. + 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: - This property has no effect if cas-group-format is not `ldap`. + .. include:: include/cas-optional.environment.md + :parser: myst_parser.sphinx_ -(cas-login)= + You can also explicitly enable/disable use of CAS support by setting the + ``CAS_ENABLED`` environment variable to ``true`` or ``false``: + + ``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. + + 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. +``` ### Controlling login behavior @@ -127,18 +133,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. @@ -149,6 +153,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/conf.py b/src/conf.py index dc642db..7351e39 100644 --- a/src/conf.py +++ b/src/conf.py @@ -40,6 +40,7 @@ extensions = [ 'guac', 'myst_parser', + 'sphinx_copybutton', 'sphinx.ext.ifconfig', 'sphinx.ext.extlinks', 'sphinx_inline_tabs' @@ -59,6 +60,10 @@ # Do not highlight source unless a Pygments lexer name is explicitly provided highlight_language = 'none' +# Exclude prompts and output lines from content copied using the copy button +copybutton_prompt_text = "$ " +copybutton_line_continuation_character = "\\" + myst_enable_extensions = [ "colon_fence", "deflist", diff --git a/src/duo-auth.md b/src/duo-auth.md index e7d5a08..075af3b 100644 --- a/src/duo-auth.md +++ b/src/duo-auth.md @@ -1,29 +1,34 @@ +--- +myst: + substitutions: + extArchiveName: guacamole-auth-duo + extJarName: guacamole-auth-duo +--- + Duo two-factor authentication ============================= -Guacamole supports Duo as a second authentication factor, layered on top -of any other authentication extension, including those available from -the main project website. The Duo authentication extension allows users -to be additionally verified against the Duo service before the -authentication process is allowed to succeed. +Guacamole's Duo authentication extension allows the third-party Duo service to +be used as an additional authentication factor for users of your Guacamole +installation. If installed, users that attempt to authenticate against +Guacamole will be sent to Duo's service for further verification. -:::{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 +``` (duo-architecture)= How Duo works with Guacamole ---------------------------- -Guacamole provides support for Duo as a second authentication factor. To -make use of the Duo authentication extension, some other authentication -mechanism will need be configured, as well. When a user attempts to log -into Guacamole, other installed authentication methods will be queried -first: +Duo is strictly a service for verifying the identities of users that have +already been partially verified through another authentication method. Thus, +for Guacamole to make use of Duo, at least one other authentication mechanism +will need be configured, such as [a supported database](jdbc-auth) or +[LDAP](ldap-auth). + +When a user attempts to log into Guacamole, other installed authentication +methods will be queried first: ![](images/duo-auth-factor-1.png) @@ -37,47 +42,8 @@ If both the initial authentication attempt and verification through Duo succeed, the user will be allowed in. If either mechanism fails, access to Guacamole is denied. -(duo-downloading)= - -Downloading the Duo extension ------------------------------ - -The Duo 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: -. - -The Duo authentication extension is packaged as a `.tar.gz` file -containing only the extension itself, `guacamole-auth-duo-1.6.0.jar`, -which must ultimately be placed in `GUACAMOLE_HOME/extensions`. - -(installing-duo-auth)= - -Installing Duo authentication ------------------------------ - -Guacamole extensions are self-contained `.jar` files which are located -within the `GUACAMOLE_HOME/extensions` directory. To install the Duo -authentication extension, you must: - -1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already - exist. - -2. Copy `guacamole-auth-duo-1.6.0.jar` within `GUACAMOLE_HOME/extensions`. - -3. Configure Guacamole to use Duo authentication, as described below. - -:::{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 Duo authentication properly, Guacamole will not start -up again until the configuration is fixed. -::: - -### Adding Guacamole to Duo +Adding Guacamole to Duo +----------------------- Duo does not provide a specific integration option for Guacamole, but Guacamole's Duo extension uses Duo's generic authentication API which @@ -101,151 +67,127 @@ hostname - they will later be specified within `guacamole.properties`: ![](images/duo-copy-details.png) +(duo-downloading)= + +Downloading and Installing the Duo extension +-------------------------------------------- + +```{include} include/ext-download.md +``` + (guac-duo-config)= -### Configuring Guacamole for Duo - -The application-specific configuration information retrieved from Duo -must be added to `guacamole.properties` to describe how Guacamole -should connect to the Duo service: - -`duo-api-hostname` -: The hostname of the Duo API endpoint to be used to verify user identities. - This will usually be in the form {samp}`api-{XXXXXXXX}.duosecurity.com`, - where {samp}`{XXXXXXXX}` is some arbitrary alphanumeric value assigned by - Duo. This value will have been generated by Duo when you added Guacamole as - a "Web SDK" application, and can be found within the application details in - the "API hostname" field. *This value is required.* - -`duo-client-id` -: The unique client ID provided for Guacamole by Duo. This value will - have been generated by Duo when you added Guacamole as a "Web SDK" - application, and can be found within the application details in the - "Client ID" field. *This value is required.* - - This value was formerly known as the "integration key" in older versions of - Duo's "Web SDK" and was configured with the `duo-integration-key` property - in older versions of Guacamole. - -`duo-client-secret` -: The shared secret provided for Guacamole by Duo. This value will have been - generated by Duo when you added Guacamole as a "Web SDK" application, and can - be found within the application details in the "Client secret" field. *This - value is required.* - - This value was formerly known as the "secret key" in older versions of Duo's - "Web SDK" and was configured with the `duo-secret-key` property in older - versions of Guacamole. - -`duo-redirect-uri` -: The URI that should be submitted to the Duo service such that they can - redirect the authenticated user back to Guacamole after the authentication - process is complete. This must be the full URL that a user would enter into - their browser to access Guacamole. *This value is required.* - -`duo-auth-timeout` -: The maximum amount of time to wait for a user to finish authenticating with - Duo, in minutes. Any authentication attempt that takes longer than this - amount of time will be rejected, requiring the user to reenter their - credentials and possibly revalidate their identity with Duo. By default, - login attempts are allowed to take up to 5 minutes. - -`duo-bypass-hosts` -: By default, when the Duo module is enabled, Duo-based MFA will be enforced - for all users, from all clients, that attempt to log in to Guacamole. - This option allows for the Duo 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 Duo - 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 Duo module will require that all users from all sources - complete the secondary authentication. - -`duo-enforce-hosts` -: Similar to the `duo-bypass-hosts` option above, this option specifies - hosts for which the Duo 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. - -:::{important} - There are two items that are important to note about the above options - for either bypassing or enforcing Duo 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 Duo 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 - `duo-bypass-hosts` property and do not specify any in the - `duo-enforce-hosts` property. In this scenario, Duo 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 - `duo-bypass-hosts` property, but you specify one or more - hosts or subnets in the `duo-enforce-hosts` property. - In this scenario, Duo 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 Duo MFA will be enforced. -::: +Configuring Guacamole for Duo +----------------------------- -(completing-duo-install)= +```{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/duo.example.properties + :language: ini + + The properties that must be set in all cases for any Guacamole installation + using Duo are: + + .. include:: include/duo.properties.md + :parser: myst_parser.sphinx_ -### Completing the installation +.. tab:: Container (Docker) -Guacamole will only reread `guacamole.properties` and load newly-installed -extensions during startup, so your servlet container will need to be restarted -before Duo authentication will take effect. Restart your servlet container and -give the new authentication a try. + 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 -:::{important} -You only need to restart your servlet container. *You do not need to restart -guacd*. + .. literalinclude:: include/duo.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/duo.example.txt + :language: console + + The environment variables that must be set in all cases for any Docker-based + Guacamole installation using Duo are: + + .. include:: include/duo.environment.md + :parser: myst_parser.sphinx_ +``` + +### Bypass/Enforce Duo for Specific Hosts + +By default, when the Duo module is enabled, Duo-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 Duo-based MFA for certain hosts and bypass it for +others. + +```{include} include/ext-client-ips.md +``` + +```{eval-rst} +.. tab:: Native Webapp (Tomcat) + + Duo-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: + + .. include:: include/duo-bypass-enforce.properties.md + :parser: myst_parser.sphinx_ + +.. tab:: Container (Docker) + + Duo-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: + + .. include:: include/duo-bypass-enforce.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 Duo support: + + .. include:: include/duo-optional.properties.md + :parser: myst_parser.sphinx_ + +.. tab:: Container (Docker) + + The following additional, optional environment variables may be set as + desired to tailor the behavior of the Duo support: + + .. include:: include/duo-optional.environment.md + :parser: myst_parser.sphinx_ + + You can also explicitly enable/disable use of Duo support by setting the + ``DUO_ENABLED`` environment variable to ``true`` or ``false``: + + ``DUO_ENABLED`` + Explicitly enables or disables use of the Duo extension. By default, the + Duo extension will be installed only if at least one Duo-related + environment variable is set. + + If set to ``true``, the Duo extension will be installed regardless of any + other environment variables. If set to ``false``, the Duo extension will + NOT be installed, even if other Duo-related environment variables have + been set. +``` + +(completing-duo-install)= -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. -::: +Completing the Installation +--------------------------- -If Guacamole does not come back online after restarting your servlet -container, check the logs. Problems in the configuration of the Duo -extension may prevent Guacamole from starting up, and any such errors -will be recorded in the logs of your servlet container. +```{include} include/ext-completing.md +``` diff --git a/src/header-auth.md b/src/header-auth.md index 2311be1..7bccc1e 100644 --- a/src/header-auth.md +++ b/src/header-auth.md @@ -1,3 +1,10 @@ +--- +myst: + substitutions: + extArchiveName: guacamole-auth-header + extJarName: guacamole-auth-header +--- + HTTP header authentication ========================== @@ -7,67 +14,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: . +```{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` +::: -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 of HTTP header authentication by + setting the ``HTTP_AUTH_ENABLED`` environment variable to ``true`` or + ``false``: + + ``HTTP_AUTH_ENABLED`` + Explicitly enables or disables use of the HTTP header authentication + extension. By default, the header authentication extension will be + installed only if at least one HTTP header-related environment variable + is set. -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. 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). + If set to ``true``, the HTTP header authentication extension will be + installed regardless of any other environment variables. If set to + ``false``, the extension will NOT be installed, even if other HTTP + header-related environment variables have been set. +``` (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 +``` diff --git a/src/include/ban.properties.in b/src/include/ban.properties.in new file mode 100644 index 0000000..591fed0 --- /dev/null +++ b/src/include/ban.properties.in @@ -0,0 +1,21 @@ +# +# The number of authentication failures ater which the extension will block +# further logins from the client IP address. This property is optional and +# the default is 5. +# +ban-max-invalid-attempts: 5 + +# +# The length of time for which a client IP address will be denied logins +# after the maximum authentication failures, in seconds. This property is +# optional and has a default value of 300 seconds (five minutes). +# +ban-address-duration: 300 + +# +# The maximum number of client IP addresses that the extension will track +# in-memory before the oldest client IP is discarded in a Least-Recently +# Used (LRU) fashion. This property is optional and has a default value +# of 10485670 (10 million IP addresses). +# +ban-max-addresses: 10485670 diff --git a/src/include/cas-optional.properties.in b/src/include/cas-optional.properties.in new file mode 100644 index 0000000..016f149 --- /dev/null +++ b/src/include/cas-optional.properties.in @@ -0,0 +1,46 @@ +# +# 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 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 diff --git a/src/include/duo-bypass-enforce.properties.in b/src/include/duo-bypass-enforce.properties.in new file mode 100644 index 0000000..e439207 --- /dev/null +++ b/src/include/duo-bypass-enforce.properties.in @@ -0,0 +1,28 @@ +# +# A comma-separated list of all IP addresses and/or subnets (in CIDR notation) +# that SHOULD NOT be required to verify themselves with Duo when +# authenticating. All other hosts in this list will required to verify against +# Duo. +# +# **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 against Duo will be +# required for all users regardless of their IP address (Duo is not bypassed +# for any addresses). +# +duo-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 with Duo when authenticating. +# All other hosts will not be required to verify against Duo. +# +# **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 against Duo will be +# required for all users regardless of their IP address (Duo is enforced for +# all addresses). +# +duo-enforce-hosts: 10.12.0.0/8 diff --git a/src/include/duo-optional.properties.in b/src/include/duo-optional.properties.in new file mode 100644 index 0000000..617ff5b --- /dev/null +++ b/src/include/duo-optional.properties.in @@ -0,0 +1,8 @@ +# +# The maximum amount of time to wait for a user to finish authenticating with +# Duo, in minutes. Any authentication attempt that takes longer than this +# amount of time will be rejected, requiring the user to reenter their +# credentials and possibly revalidate their identity with Duo. By default, +# login attempts are allowed to take up to 5 minutes. +# +duo-auth-timeout: 5 diff --git a/src/include/duo.properties.in b/src/include/duo.properties.in new file mode 100644 index 0000000..9785b21 --- /dev/null +++ b/src/include/duo.properties.in @@ -0,0 +1,41 @@ +# +# The hostname of the Duo API endpoint to be used to verify user identities. +# This will usually be in the form {samp}`api-{XXXXXXXX}.duosecurity.com`, +# where {samp}`{XXXXXXXX}` is some arbitrary alphanumeric value assigned by +# Duo. This value will have been generated by Duo when you added Guacamole as +# a "Web SDK" application, and can be found within the application details in +# the "API hostname" field. *This value is required.* +# +duo-api-hostname: api-XXXXXXXX.duosecurity.com + +# +# The unique client ID provided for Guacamole by Duo. This value will +# have been generated by Duo when you added Guacamole as a "Web SDK" +# application, and can be found within the application details in the +# "Client ID" field. *This value is required.* +# +# This value was formerly known as the "integration key" in older versions of +# Duo's "Web SDK" and was configured with the `duo-integration-key` property +# in older versions of Guacamole. +# +duo-client-id: XXXXXXXXXXXXXXXXXXXX + +# +# The shared secret provided for Guacamole by Duo. This value will have been +# generated by Duo when you added Guacamole as a "Web SDK" application, and can +# be found within the application details in the "Client secret" field. *This +# value is required.* +# +# This value was formerly known as the "secret key" in older versions of Duo's +# "Web SDK" and was configured with the `duo-secret-key` property in older +# versions of Guacamole. +# +duo-client-secret: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + +# +# The URI that should be submitted to the Duo service such that they can +# redirect the authenticated user back to Guacamole after the authentication +# process is complete. This must be the full URL that a user would enter into +# their browser to access Guacamole. *This value is required.* +# +duo-redirect-uri: https://myguac.example.net diff --git a/src/include/ext-client-ips.md b/src/include/ext-client-ips.md new file mode 100644 index 0000000..9ad0122 --- /dev/null +++ b/src/include/ext-client-ips.md @@ -0,0 +1,11 @@ +:::{warning} +If you will be configuring Guacamole to consider users' IP addresses, **it is +important to make sure that Guacamole is receiving correct IP address +information for all clients**. + +If Guacamole is behind a reverse proxy, such as for SSL termination, the IP +addresses of all users will appear to be the IP address of the proxy unless +additional configuration steps are taken. **Be sure to follow [the +documentation for configuring forwarding of client IP +information](reverse-proxy)!** +::: diff --git a/src/include/ext-completing.md b/src/include/ext-completing.md new file mode 100644 index 0000000..1e4ab14 --- /dev/null +++ b/src/include/ext-completing.md @@ -0,0 +1,36 @@ +::::{tab} Native Webapp (Tomcat) +Guacamole will only reread its configuration and load newly-installed +extensions during startup, so Tomcat will need to be restarted before these +changes can take effect. Restart Tomcat and give the new functionality a try. + +*You do not need to restart guacd*. + +:::{hint} +If Guacamole does not come back online after restarting Tomcat, **check the +logs**. Configuration problems may prevent Guacamole from starting up, and any +such errors will be recorded in Tomcat's logs. +::: +:::: + +::::{tab} Container (Docker) +The environment variables that configure the behavior of Docker can only be set +at the time the Docker container is created. To apply these configuration +changes, you will need to recreate the container. + +If your Guacamole container was deployed using Docker Compose: +: Simply making the desired changes to your `docker-compose.yml` and running + `docker compose up` is sufficient. Docker Compose will automatically + recognize that the environment variables of the container have changed and + recreate it. + +If your Guacamole container was deployed manually (using `docker run`): +: You wll need to manually use `docker rm` to remove the old container and then + manually recreate it with `docker run` and the new environment variables. + +:::{hint} +If Guacamole does not come back online after recreating the container, **check +the Docker logs**. Configuration problems may prevent Guacamole from starting +up, and any such errors will be recorded in the Docker logs for the Guacamole +container. +::: +:::: diff --git a/src/include/ext-download.md b/src/include/ext-download.md new file mode 100644 index 0000000..a694aee --- /dev/null +++ b/src/include/ext-download.md @@ -0,0 +1,44 @@ +Guacamole is configured differently depending on whether Guacamole was +[installed natively](installing-guacamole) or [using the provided Docker +images](guacamole-docker). The documentation here covers both methods. + +If you have installed Guacamole natively under [Apache Tomcat](https://tomcat.apache.org/) or similar: +: You will need to modify the + contents of `GUACAMOLE_HOME` ([Guacamole's configuration + directory](guacamole-home)), which is located at `/etc/guacamole` by default + and may need to be created first. + + 1. Download {{ '' + + extArchiveName + '-' + version + '.tar.gz' }} from {{ 'the release + notes' }} and extract it. + + 2. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already + exist. + + 3. Copy the {{ '' + extJarName + + '-' + version + '.jar' }} file from the contents of the archive to + `GUACAMOLE_HOME/extensions/`. + + 4. Proceed with the configuring Guacamole for the newly installed extension as + described below. The extension will be loaded after Guacamole has been + restarted. + +If you have installed Guacamole using the provided Docker images: +: There is no need to download anything! The `guacamole/guacamole` Docker image + bundles all supported extensions and automatically manages `GUACAMOLE_HOME` + for you based on environment variables. + +:::{note} +Download and documentation links for all officially supported extensions for a +particular version of Guacamole are always provided in the release notes for +that version. The copy of the documentation you are reading now is from {{ + 'Apache Guacamole ' + version + '' +}}. + +**If you are using a different version of Guacamole, please locate that version +within [the release archives](https://guacamole.apache.org/releases/) and +consult the documentation for that release instead.** +::: + + diff --git a/src/include/http-auth.properties.in b/src/include/http-auth.properties.in new file mode 100644 index 0000000..b32d407 --- /dev/null +++ b/src/include/http-auth.properties.in @@ -0,0 +1,9 @@ +# +# 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 diff --git a/src/include/json-optional.properties.in b/src/include/json-optional.properties.in new file mode 100644 index 0000000..90eb164 --- /dev/null +++ b/src/include/json-optional.properties.in @@ -0,0 +1,12 @@ +# +# 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 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/include/ksm-optional.properties.in b/src/include/ksm-optional.properties.in new file mode 100644 index 0000000..4301a6e --- /dev/null +++ b/src/include/ksm-optional.properties.in @@ -0,0 +1,24 @@ +# +# Whether unverified server certificates should be accepted. If set to `true`, +# the server certificate for connections to the KSM service will be accepted even +# if they cannot be verified. **Unless you are a developer testing changes to +# the KSM vault support itself, it is unlikely that you need to set this +# property.** +# +ksm-allow-unverified-cert: false + +# +# Specify the minimum number of milliseconds between calls to the KSM API. The +# API allows a limited number of calls per month, and calls over the included +# amount generate additional cost. Setting this property allows you to +# limit Guacamole's impact on that cost. +# +ksm-api-call-interval: 300000 + +# +# Whether or not the Windows domain should be stripped off of the username +# when usernames are retrieved from the KSM vault and placed into its own +# secret. This is optional, and by default it is false - domains will +# not be stripped from the username. +# +ksm-strip-windows-domains: false diff --git a/src/include/ksm-user-vaults.properties.in b/src/include/ksm-user-vaults.properties.in new file mode 100644 index 0000000..b8adedc --- /dev/null +++ b/src/include/ksm-user-vaults.properties.in @@ -0,0 +1,7 @@ +# +# Whether or not users should be allowed to set their own KSM configuration, +# which will be used to pull secrets _only_ when not already provided by the +# global or connection-group-level KSM configuration. A user-level KSM +# configuration will never be used if a matching secret is otherwise available. +# +ksm-allow-user-config: false diff --git a/src/include/ksm.properties.in b/src/include/ksm.properties.in new file mode 100644 index 0000000..f0d891b --- /dev/null +++ b/src/include/ksm.properties.in @@ -0,0 +1,7 @@ +# +# The base64-encoded configuration information generated for the application +# you created within KSM to represent Apache Guacamole. The easiest way to +# obtain this value is using [the KSM CLI tool](https://docs.keeper.io/secrets-manager/secrets-manager/secrets-manager-command-line-interface/init-command). +# as described above. *This value is required.* +# +ksm-config: ewogICJjbGllbnRJZCI6ICJTR1ZzYkc4Z2RHaGxjbVVoSUZSb1pYTmxJSEJ5YjNC... diff --git a/src/include/quickconnect.properties.in b/src/include/quickconnect.properties.in new file mode 100644 index 0000000..852e6b7 --- /dev/null +++ b/src/include/quickconnect.properties.in @@ -0,0 +1,18 @@ +# +# An optional list of parameters that are allowed to be used by connections +# that are created and accessed via the quickconnect extension. If this +# property is present, only parameters in this list will be allowed. If this +# property is absent, any/all parameters will be allowed unless explicitly +# denied using the `quickconnect-denied-parameters` property. +# +quickconnect-allowed-parameters: hostname, port + +# +# An optional list of parameters that are explicitly denied from being used by +# connections created and accessed via the quickconnect extension. If this +# property is present, any parameters in this list will be removed from the +# connection configuration when it is created, *even if those parameter are +# listed above in the `quickconnect-allowed-parameters` property.* If this +# property is not present, no connection parameters will be explicitly denied. +# +quickconnect-denied-parameters: enable-drive, drive-path diff --git a/src/include/totp-bypass-enforce.properties.in b/src/include/totp-bypass-enforce.properties.in new file mode 100644 index 0000000..ce06bcf --- /dev/null +++ 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 new file mode 100644 index 0000000..165d08c --- /dev/null +++ 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/include/warn-config-changes.md b/src/include/warn-config-changes.md new file mode 100644 index 0000000..2ca025e --- /dev/null +++ b/src/include/warn-config-changes.md @@ -0,0 +1,10 @@ +:::{warning} +You will need to restart the Guacamole web application in order to complete +configuration. Doing this will disconnect all active users, so please: + +* **Do this only at a time that you can tolerate service unavailability**, such + as a scheduled maintenance window. + +* Keep in mind that **configuration errors may prevent Guacamole from starting + back up**. +::: diff --git a/src/json-auth.md b/src/json-auth.md index 04a380e..6aa01e0 100644 --- a/src/json-auth.md +++ b/src/json-auth.md @@ -1,3 +1,10 @@ +--- +myst: + substitutions: + extArchiveName: guacamole-auth-json + extJarName: guacamole-auth-json +--- + Encrypted JSON authentication ============================= @@ -8,71 +15,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) + + The following additional, optional environment variables may be set as + desired to tailor the encrypted JSON authentication: -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: + .. include:: include/json-optional.environment.md + :parser: myst_parser.sphinx_ - $ echo -n "ThisIsATest" | md5sum - 4c0b569e4c96df157eee1b65dd0e4d41 - + You can also explicitly enable/disable use of encrypted JSON authentication + by setting the ``JSON_ENABLED`` environment variable to ``true`` or + ``false``: -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: + ``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. - json-secret-key: 4c0b569e4c96df157eee1b65dd0e4d41 + 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)= diff --git a/src/totp-auth.md b/src/totp-auth.md index 8b4b3ad..c06ec6d 100644 --- a/src/totp-auth.md +++ b/src/totp-auth.md @@ -1,3 +1,10 @@ +--- +myst: + substitutions: + extArchiveName: guacamole-auth-totp + extJarName: guacamole-auth-totp +--- + TOTP two-factor authentication ============================== @@ -8,12 +15,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 +123,119 @@ 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: . +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 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. + If your intended authentication application or device has different + requirements, or you wish to override the defaults, additional environment + variables may be set: -:::{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. -::: + .. 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``: -(completing-totp-install)= + ``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. -### Completing the installation + 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. +``` -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. +### Bypass/Enforce TOTP for Specific Hosts -:::{important} -You only need to restart your servlet container. *You do not need to restart -guacd*. +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. -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/ext-client-ips.md +``` + +```{eval-rst} +.. tab:: Native Webapp (Tomcat) + + 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: + + .. include:: include/totp-bypass-enforce.properties.md + :parser: myst_parser.sphinx_ + +.. tab:: Container (Docker) + + 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: + + .. 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. diff --git a/src/vault.md b/src/vault.md index 90dd12b..b6608ae 100644 --- a/src/vault.md +++ b/src/vault.md @@ -1,3 +1,10 @@ +--- +myst: + substitutions: + extArchiveName: guacamole-vault + extJarName: ksm/guacamole-vault-ksm +--- + Retrieving secrets from a vault =============================== @@ -8,53 +15,17 @@ properties via an additional, vault-specific configuration file analogous to `guacamole.properties`. This support is intended with multiple vault providers in mind and currently supports [Keeper Secrets Manager (KSM)](https://www.keepersecurity.com/secrets-manager.html). -:::{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. -::: - -(vault-downloading)= - -Downloading the vault extension -------------------------------- - -The vault 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: -. - -The vault extension is packaged as a `.tar.gz` file containing directories -specific to vault implementations (currently only `ksm/` for the KSM -implementation). Each vault-specific directory contains a `.jar` file (the -actual Guacamole extension). The Guacamole extension `.jar` will ultimately -need to be placed within `GUACAMOLE_HOME/extensions`. -(installing-vault-support)= - -Installing key vault support ----------------------------- - -Guacamole extensions are self-contained `.jar` files which are located within -the `GUACAMOLE_HOME/extensions` directory. To install the KSM vault extension, -you must: - -1. Create the `GUACAMOLE_HOME/extensions` directory, if it does not already - exist. +```{include} include/warn-config-changes.md +``` -2. Copy `ksm/guacamole-vault-ksm-1.6.0.jar` within `GUACAMOLE_HOME/extensions`. +(vault-downloading)= -3. Configure Guacamole to use KSM to retrieve secrets, as described below. +Downloading and installing the vault extension +---------------------------------------------- -:::{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 vault support properly, Guacamole will not start up -again until the configuration is fixed. -::: +```{include} include/ext-download.md +``` (adding-guac-to-ksm)= @@ -141,7 +112,8 @@ question should be able to access. (guac-vault-config)= -### Configuring Guacamole for KSM +Configuring Guacamole for KSM +----------------------------- Guacamole requires only a single configuration property to configure secret retrieval from KSM, `ksm-config`, which must be provided the base64 @@ -149,77 +121,160 @@ configuration value retrieved from KSM using the one-time token [obtained when Guacamole was registered with KSM as an application as described above](adding-guac-to-ksm). All other configuration properties are optional. -`ksm-config` -: The base64-encoded configuration information generated for the application - you created within KSM to represent Apache Guacamole. The easiest way to - obtain this value is using [the KSM CLI tool](https://docs.keeper.io/secrets-manager/secrets-manager/secrets-manager-command-line-interface/init-command). - as described above. *This value is required.* - -`ksm-allow-unverified-cert` -: Whether unverified server certificates should be accepted. If set to `true`, - the server certificate for connections to the KSM service will be accepted even - if they cannot be verified. **Unless you are a developer testing changes to - the KSM vault support itself, it is unlikely that you need to set this - property.** - -`ksm-api-call-interval` -: Specify the minimum number of milliseconds between calls to the KSM API. The - API allows a limited number of calls per month, and calls over the included - amount generate additional cost. Setting this property allows you to - limit Guacamole's impact on that cost. - -`ksm-strip-windows-domains` -: Whether or not the Windows domain should be stripped off of the username - when usernames are retrieved from the KSM vault and placed into its own - secret. This is optional, and by default it is false - domains will - not be stripped from the username. - -`ksm-allow-user-config` -: Whether or not users should be allowed to set their own KSM configuration, - which will be used to pull secrets _only_ when not already provided by the - global or connection-group-level KSM configuration. I.E. a user-level KSM - configuration will never be used if a matching secret is otherwise available. - -#### User and Connection Group KSM Configuration - -In addition to the required global `ksm-config` configuration blob, Guacamole -can also be configured with user or connection group KSM configuration, which -will pull additional secrets _only_ when not already available. If a secret can -be pulled using the `ksm-config` global KSM config, it will always be used. -Failing that, if a secret is available using the connection grop config, that -value will be used. Only when neither the global or containing connection group -KSM configs define a secret will the user KSM config be used. Note also that -user KSM configs will be disabled unless the global `ksm-allow-user-config` and -per-connection `ksm-user-config-enabled` attribute are both set to true. - -These KSM config values can be set directly in the webapp, on the [connection -group edit page](connection-group-management), and on the [user preferences page](preferences). -Unlike the `ksm-config` global configuration, either the base64-encoded configuration -provided by Keeper Commander can be used, or the one-time token can be used directly. +```{eval-rst} +.. tab:: Native Webapp (Tomcat) -(completing-vault-install)= + If deploying Guacamole natively, you will need to add a section to your + ``guacamole.properties`` that looks like the following: -### Completing the installation + .. literalinclude:: include/ksm.example.properties + :language: ini -Guacamole will only reread `guacamole.properties` and load newly-installed -extensions during startup, so your servlet container will need to be restarted -before the newly-installed vault support will take effect. Restart your servlet -container and give the vault support a try. + There is only a single property that must be set in all cases for any + Guacamole installation using KSM: -:::{important} -You only need to restart your servlet container. *You do not need to restart -guacd*. + .. include:: include/ksm.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/ksm.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/ksm.example.txt + :language: console + + There is only a single environment variable that must be set in all cases + for any Guacamole installation using KSM: -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/ksm.environment.md + :parser: myst_parser.sphinx_ +``` + +### Additional vaults for users and connection groups + +In addition to the required, application-wide vault, Guacamole can be +configured to additionally pull secrets from separate vaults that are declared +at the user or connection group level. The configuration information for these +vaults can be set directly in the webapp, on the [connection group edit +page](connection-group-management) and on the [user preferences +page](preferences). + +:::{hint} +Unlike the application-wide vault (which must always be configured using a +lengthy blob of base64-encoded data), a one-time token obtained from KSM can be +used in these cases. ::: -If Guacamole does not come back online after restarting your servlet container, -check the logs. Problems in the configuration of installed vault support -extensions may prevent Guacamole from starting up, and any such errors will be -recorded in the logs of your servlet container. +```{eval-rst} +.. tab:: Native Webapp (Tomcat) + + Because it is not necessarily desirable that users be able to provide their own + secrets for use within connections, administrators must explicitly enable this + functionality by: + + 1. Setting the property ``ksm-allow-user-config`` property to ``true``, as + described below. + 2. Checking the "Allow user-provided KSM configuration" box on any + connection that should be allowed to consume user-specific secrets. + + **Secrets from a user-specific vault will not be used unless both of the + above conditions are true.** + + .. include:: include/ksm-user-vaults.properties.md + :parser: myst_parser.sphinx_ + +.. tab:: Container (Docker) + + Because it is not necessarily desirable that users be able to provide their own + secrets for use within connections, administrators must explicitly enable this + functionality by: + + 1. Setting the property ``KSM_ALLOW_USER_CONFIG`` environment variable to + ``true``, as described below. + 2. Checking the "Allow user-provided KSM configuration" box on any + connection that should be allowed to consume user-specific secrets. + + **Secrets from a user-specific vault will not be used unless both of the + above conditions are true.** + + .. include:: include/ksm-user-vaults.environment.md + :parser: myst_parser.sphinx_ + +``` + +#### Priorities of multiple vaults + +When multiple vaults apply to any connection attempt, secrets are pulled and +applied in a specific order of priority that is intended to ensure the +administrator always has ultimate control over the behavior of a connection: + +1. **Application-wide vault:** Secrets are always pulled from the + application-wide vault first (the vault provided with the `ksm-config` + property). + +2. **Connection group vault:** If a particular secret is not available within + the application-wide vault, but the connection is within a connection group + that has been configured with a KSM vault, the vault configured for that + connection group is used to reattempt retrieving the secret. + +3. **User-specific vault:** If a particular secret is not available within + any other administator-controlled vault, the connection in question has + been configured to allow user-specific vault use, and the current user has + configured such a vault, that vault will be used to reattempt retrieving the + secret. + +By design, the application-wide vault always has the highest priority, and any +administrator-controlled vault always has priority over user-controlled vaults. + +### 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 KSM support: + + .. include:: include/ksm-optional.properties.md + :parser: myst_parser.sphinx_ + +.. tab:: Container (Docker) + + The following additional, optional environment variables may be set as + desired to tailor the KSM support: + + .. include:: include/ksm-optional.environment.md + :parser: myst_parser.sphinx_ + + You can also explicitly enable/disable use of KSM by setting the + ``KSM_ENABLED`` environment variable to ``true`` or ``false``: + + ``KSM_ENABLED`` + Explicitly enables or disables use of the KSM extension. By default, the + KSM extension will be installed only if at least one related environment + variable is set. + + If set to ``true``, the KSM extension will be installed regardless of any + other environment variables. If set to ``false``, the KSM extension will + NOT be installed, even if other related environment variables have been set. +``` + + +(completing-vault-install)= + +Completing the installation +--------------------------- + +```{include} include/ext-completing.md +``` (vault-connection-secrets)=