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>
