mike-jumper commented on code in PR #217:
URL: https://github.com/apache/guacamole-manual/pull/217#discussion_r1385743376
##########
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:
@bogdantomasciuc, I don't believe this is correct. Copying from my comment
in JIRA:
> ... the time comparisons involved in TOTP do not involve your local
timezone. All calculations are done with timestamps pulled from a system clock
that is _always_ UTC.
For example, here's how the codes are calculated:
1. `generate()` is invoked on `TOTPGenerator` that has been initialized with
the user's TOTP key.
https://github.com/apache/guacamole-client/blob/eb2a068f4dbc24602c906b14782bbc1c8dc52aec/extensions/guacamole-auth-totp/src/main/java/org/apache/guacamole/auth/totp/user/UserVerificationService.java#L344-L345
2. `TOTPGenerator` pulls the current system timestamp using
`System.currentTimeMillis()`, which returns a timestamp based on UTC.
https://github.com/apache/guacamole-client/blob/eb2a068f4dbc24602c906b14782bbc1c8dc52aec/extensions/guacamole-auth-totp/src/main/java/org/apache/guacamole/totp/TOTPGenerator.java#L427-L429
From [the documentation for
`System.currentTimeMillis()`](https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#currentTimeMillis--),
that value is (emphasis added):
> the difference, measured in milliseconds, between the current time and
**midnight, January 1, 1970 UTC.**
Local timezone settings have no bearing on this. Setting `TZ` will affect
how command-line tools present the current system time to you, but this should
have no impact at all on the calculations involved in producing a TOTP code.
--
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
