This is an automated email from the ASF dual-hosted git repository. mjumper pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/guacamole-manual.git
commit 9134610571b6cece4a27e2f8bbc0d65d65ea0ba1 Author: Nick Couchman <nick.couch...@yahoo.com> AuthorDate: Mon Nov 2 10:11:37 2020 -0500 GUACAMOLE-221: Document connection parameter prompting. --- src/chapters/configuring.xml | 60 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 51 insertions(+), 9 deletions(-) diff --git a/src/chapters/configuring.xml b/src/chapters/configuring.xml index dc96a8e..0ddefba 100644 --- a/src/chapters/configuring.xml +++ b/src/chapters/configuring.xml @@ -1635,15 +1635,18 @@ tcp6 0 0 :::4713 :::* LISTEN</comp domain parameters are omitted. One notable exception to this is Network Level Authentication, or NLA, which performs all authentication outside of a desktop session, and thus in the absence of a graphical interface.</para> - <important> - <para>If your server requires NLA, you <emphasis>must</emphasis> provide a - username and password. Leveraging Guacamole's <link - xmlns:xlink="http://www.w3.org/1999/xlink" linkend="parameter-tokens" - >parameter tokens</link> and <link - xmlns:xlink="http://www.w3.org/1999/xlink" linkend="ldap-auth">LDAP - support</link> to integrate with Active Directory and automatically pass - through credentials is a common configuration.</para> - </important> + <para>Servers that require NLA can be handled by Guacamole in one of two ways. The + first is to provide the username and password within the connection + configuration, either via static values or by passing through the Guacamole + credentials with <link xmlns:xlink="http://www.w3.org/1999/xlink" + linkend="parameter-tokens">parameter tokens</link> and + <link xmlns:xlink="http://www.w3.org/1999/xlink" linkend="ldap-auth"> + LDAP support</link>. Alternatively, if credentials are not configured + within the connection configuration, Guacamole will attempt to prompt the user + for the credentials interactively, if the versions of both guacd and + Guacamole Client in use support it. If either component does not support + prompting and the credentials are not configured, NLA-based connections will + fail.</para> <informaltable frame="all"> <indexterm> <primary>parameters</primary> @@ -1730,6 +1733,13 @@ tcp6 0 0 :::4713 :::* LISTEN</comp session actually starts, avoiding the need for the Windows server to allocate significant resources for users that may not be authorized.</para> + <para>If the versions of guacd and Guacamole Client + in use support prompting and the username, password, + and domain are not specified, the user will be + interactively prompted to enter credentials to + complete NLA and continue the connection. Otherwise, + when prompting is not supported and credentials are + not provided, NLA connections will fail.</para> </listitem> </varlistentry> <varlistentry> @@ -6195,6 +6205,38 @@ guaclog: INFO: All files interpreted successfully.</computeroutput> </section> </section> </section> + <section xml:id="parameter-prompting"> + <title>Parameter prompting</title> + <para><indexterm> + <primary>parameters</primary> + <secondary>prompt</secondary> + </indexterm>In certain situations Guacamole may determine that additional + information is required in order to successfully open or continue a + connection. In these scenarios guacd will send an instruction back to + the client to retrieve that information, which will result in the user + being prompted for those additional parameters.</para> + <para>Currently the only parameters that will trigger this prompt to the + user are authentication requests for the RDP and VNC protocols where + authenticators were not provided as part of the connection configuration. + </para> + <important> + <para>It is important to note that requests for parameters will only be + generated in the case where that information has not already been + provided as part of the connection. The user will never be asked for + parameters that replace or override connection parameters where + values have been configured as part of the connection, including + authentication information. For example, if the configuration of + a connection to a RDP server specifies a username and password, + and that username or password is incorrect and results in an + authentication failure, Guacamole will not prompt the user for + additional credentials. For RDP servers where NLA is enforced, + this will result in a connection failure. Other RDP servers may + behave differently and give the user the ability to try other + credentials, but this is outside the control of Guacamole - + Guacamole will not override pre-configured values with input + from the user.</para> + </important> + </section> </section> <section xml:id="guacd.conf"> <title>Configuring guacd</title>