bogdantomasciuc commented on code in PR #217:
URL: https://github.com/apache/guacamole-manual/pull/217#discussion_r1386086112
##########
src/guacamole-docker.md:
##########
@@ -791,6 +791,62 @@ SAML authentication extension.
that may be helpful in debugging problems with SAML authentication. This
is optional and defaults to false - debugging will not be enabled.
+(guacamole-docker-totp-auth)=
+
+### TOTP Authentication
+
+TOTP authentication can be configured to allow the Guacamole Client instance
+running in a Docker container to use a second layer of authentication using a
+two factor authenticator application and short one-time codes. More details
+on TOTP authentication with Guacamole can be found on the [](totp-auth) page.
+
+(guacamole-totp-auth-required-vars)=
+
+#### Required environment variables
+
+Configuration of TOTP authentication requires that the following enviroment
+variable be provided to the container:
+
+`TOTP_ENABLED`
+: If the environment variable is provided with the value of "true" then the
+ extension is enabled inside the docker container.
+
+(guacamole-docker-totp-auth-optional-vars)=
+
+#### Optional environment variables
+
+Other environment variables can be provided to adjust the behavior of the
+TOTP authentication extension.
+
+`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.
+
+:::{important}
+The duration and/or hash algorithm are not settable in some widely used
autenticator
+apps. Setting these value to something other than the defaults might make the
codes
+unusable if your authenticator app does not support setting these parameters.
+:::
+
+Depending on your server's timezone, because the extension relies on working
with
+short lived codes, in order to make the extension work reliable one may have to
+provide the correct timezone to the docker containers. Writing correct codes
on the
+authentication page but getting authentication error might indicate a timezone
issus.
+The correct timezone can be passed with the variable `TZ` as in
`TZ="Europe/Bucharest"`,
+for example.
Review Comment:
Your comment and the provided documentation makes sense, but still, unless
TZ is provided to the containers, the totp authentication fails consistently on
my installation. I am using bare simple docker run commands (if it matters)
with mysql backend. This is the (obviously edited :D) command:
```bash
docker run --name guacd --restart=always -v
/GuacamoleRecordings:/var/lib/guacamole/recordings -e GUACD_LOG_LEVEL="info" -e
TZ=Europe/Bucharest -d guacamole/guacd:latest
docker run --name guac-mysql --mount source=guac-mysql,target=/var/lib/mysql
-v /tmp/scripts:/tmp/scripts -e MYSQL_ROOT_PASSWORD='SomeS3cr3tPassw0rd' -e
TZ=Europe/Bucharest --restart=always -d mysql:latest
docker run --name guacamole --link guacd:guacd --link guac-mysql:mysql -v
/var/log/guacamole:/home/guacamole/logs -v
/GuacamoleRecordings:/var/lib/guacamole/recordings -e
MYSQL_DATABASE='guacamole-db' -e MYSQL_USER='guacamole-user' -e
MYSQL_PASSWORD='MyguacamoleV3ryS3cr3tPassw0rd!ssst!' -e
REMOTE_IP_VALVE_ENABLED='true' --mount source=guac-config,target=/config -e
GUACAMOLE_HOME=/config -e RECORDING_SEARCH_PATH='/var/lib/guacamole/recordings'
-e LOG_LEVEL='info' -e TOTP_ENABLED='true' -e TZ='Europe/Bucharest'
--restart=always -d -p 8080:8080 guacamole/guacamole:latest
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscr...@guacamole.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
