FWD

Web Client Setup¶

• Web Client Setup
  • System Requirements
  • Setup
  • Under The Hood

This chapter documents how to configure and setup the FWD Server to allow access to the FWD Clients via a web browser (a different client than the Swing Applet). The Web Clients were implemented to allow access to a ChUI/GUI FWD Client running remotely on another machine (note that at the time of this writing only ChUI clients - using the Console Driver - can be accessed via a browser). Once all setup is performed, when accessing the remote FWD Client via the web browser, the user will have the same experience as if the user has connected to the remote machine and started the FWD Client there, manually: this means that the user will have the same OS security permissions and will be allowed to start processes, read files, access a shell to that machine, etc. But, an inherent limitation for the web clients is that they can start only processes which remain active in the same console window as the application client.

TBD: Add discussion for Spawner Setup and Configuration, Remote Launchers and Reverse Proxy.

System Requirements¶

The FWD Web Client should be able to run on any web browser which supports HTML5, Web Sockets and AJAX requests. At the time of this writing, the web client is expected to work properly with the latest versions of the Google Chrome, Mozilla Firefox, Internet Explorer and Safari browsers; from these, testing showed that the most reliable (in terms of performance and stability) is Google Chrome.

Considering how the dedicated web server (ran by each remote FWD Client, see the Under the Hood section, for more details) computes its dedicated port, it is best for the machine on which the remote FWD Client is launched to be directly accessible from the machine used by the user to start the Web Client (i.e. no intermediate NAT-enabled router is required to access the FWD application server). If this is not set then the embedded web server (upon which the web client depends) will not be started at server startup. No error messages will be written to the log. The core idea is that there is no support for insecure web protocols.

The last requirement is that an user allowed to connect to the FWD application server via a web browser needs to have access to valid OS credentials on the remote machine on which the remote FWD Client is started (which at the time of this writing is the same machine on which the FWD application server is running). Without valid credentials, the user will not be allowed to pass the initial login page.

Setup¶

TBD: Needs updates to document the full range of current configuration and options.

To access web clients, it is required for the FWD server to have the spawner tool configured properly - as the spawner is not used only for launching web clients, details about its setup can be found in the Application Server Installation chapter of this book. This chapter assumes the client spawner tool is setup properly.

In addition to the spawner, the FWD server itself must be configured with a secure port. This is defined in the bootstrap configuration or is passed as a bootstrap configuration override on the server driver command line. The values that must be set include net:connection:secure=true and net:server:secure_port=<port>. For more details on this, please see Part 2: Bootstrap Configuration.

The remaining configuration is all related to the FWD server directory, which instructs how the terminal will be displayed in the web browser. The directory node is named chuiWeb and can reside either in /server/default/ or the /server/<server-id>/ section, with the later having priority over the default configuration; also, if a chuiWeb/<@node@>/ node is found in both per-server and default configuration, the per-server value will be used. The following table describe all the possible configurations (all nodes are children of the chuiWeb/ node), their default values and meaning.

chuiWeb/ Node	Type	Default Value	Mandatory	Description
enabled	boolean	false	yes	Flag identifying if this application server is configured for launching web clients.
port	integer	0	no	An explicit port to start the FWD Client's embedded web server or 0 to let the OS assign one. If an explicit port is used, then only one web client can be connected at at time.
host	string	n/a	no	An explicit host to start the FWD Client's embedded web server or use the server's host, if not specified. At the time of this writing, there is a limitation when running the web clients: this node needs to be configured so that it mentions the server's host used to access the web client, so that the redirect will land on the same domain as the initial login page. If the domains for the login page and redirect are not the same, a HTTP ERROR: 403 – Forbidden error page will be displayed.
background	string	0x000000(color Black)	no	The background color for each character. This can either be the hex-representation of a color (including the 0x prefix) or a color name.
foreground	string	0xFFA500	no	The foreground color for each character. This can either be the hex-representation of a color (including the 0x prefix) or a color name.
selection	string	0x0000FF(color Blue)	no	The color of the box when the user selects a rectangle of text. This can either be the hex-representation of a color (including the 0x prefix) or a color name.
fontname	string	Monospaced	no	The font used for all text. Must be a fixed-size font.
fontsize	integer	12	no	The font's point size used for all text.
rows	integer	24	no	The number of rows of text on the terminal screen.
columns	integer	80	no	The number of columns of text on the terminal screen.
webSocketTimeout	integer	-1	no	Web socket timeout (in milliseconds). This is a timeout after which the web socket is closed .
watchdogTimeout	integer	-1	no	Watchdog timeout (in milliseconds). After the web socket is closed, the watchdog will wait at least that certain amount of time and, if the web socket was connected again, it will decide to terminate the FWD client, as the remote user is no longer connected to it. A value of -1 will mean the remote FWD client will be terminated as soon as the web socket is closed.

Considering the table above, the minimal chuiWeb/ node looks like:

<node class="container" name="chuiWeb">
   <node class="boolean" name="enabled">
      <node-attribute name="value" value="TRUE"/>
   </node>
</node>

while the full node looks like:

<node class="container" name="chuiWeb">
   <node class="boolean" name="enabled">
      <node-attribute name="value" value="TRUE" />
   </node>
   <node class="string" name="background">
      <node-attribute name="value" value="0x000000" />
   </node>
   <node class="string" name="foreground">
      <node-attribute name="value" value="0xFFA500" />
   </node>
   <node class="string" name="selection">
      <node-attribute name="value" value="0x0000FF" />
   </node>
   <node class="string" name="fontname">
      <node-attribute name="value" value="monospaced" />
   </node>
   <node class="integer" name="fontsize">
      <node-attribute name="value" value="12" />
   </node>
   <node class="integer" name="rows">
      <node-attribute name="value" value="24" />
   </node>
   <node class="integer" name="columns">
      <node-attribute name="value" value="80" />
   </node>
   <node class="integer" name="webSocketTimeout">
      <node-attribute name="value" value="-1" />
   </node>
   <node class="integer" name="watchdogTimeout">
      <node-attribute name="value" value="300000" />
   </node>
   <node class="integer" name="port">
      <node-attribute name="value" value="9443" />
   </node>
   <node class="string" name="host">
      <node-attribute name="value" value="localhost" />
   </node>
</node>

Under The Hood¶

This section documents the implementation details of the web client.

Web Client Modes¶

The following shows the different modes of the web client.

TBD: More discussion, include ChUI as well.

Spawning a Web Client¶

TBD: Add descriptions for both embedded mode forms. Add spawner flow and description for ChUI.

This description is out of date. It needs to be updated to match the above diagram.

This section describes how the FWD Server and the remote FWD Client react, when the user accesses a Web Client:

1. The process with the user opening a browser session with the FWD server (running an embedded Jetty instance on the same port as the administration console). The URL will look like https://localhost:<port>/chui , where <port> is the port configured in the adminPort directory configuration, in the server section (default or per-server). Depending on your browser configuration and how the server's SSL certificate was generated, the browser might show you an “untrusted connection” message and ask you to accept the certificate before continuing, on the first connection to this host and port.
2. The FWD server sends down a login page, which looks like:
   
3. The user inputs their operating system level user credentials (e.g. Linux userid and password) and submits the form.
4. Using the spawner tool (see the Application Server Installation chapter for how to install the spawner), the FWD server thus launches a new FWD client (as a child process) and part of that "spawn" processing is an OS-level login. If the given credentials are authentic/correct, the child process is not only launched, but it has the user's context at the OS level. In other words, the process is run under the user's id and has full access to that user's files/configuration/rights.
5. The FWD client has its own embedded web server. After successfully launching and initializing, it provides URL information back to the FWD server to allow a connection to the FWD client's web server.
6. The FWD server sends a redirect response back to the user's initial browser session. This also includes an authorization token that allows the FWD client to ensure that only that browser session may access that web server.
7. The user's browser session redirects to the FWD client's web server. This web server is ran using the server's certificate, so the browser might show you an “untrusted connection” message and ask you to accept the certificate before continuing, on the first connection to this host and port. And if the port is randomly assigned, this will mean each time a new port is reached, the “untrusted connection” message will be displayed.
   If you are encountering a HTTP ERROR: 403 - Forbidden page after the redirect, note at the time of this writing there is a limitation for web clients: the chuiWeb/host node needs to be configured so that it mentions the server's host used to access the web client.
8. The FWD client's web server sends back the "main" page which is mostly Javascript.
9. The loaded page establishes a bidirectional websocket to the FWD client.
10. At this point the ChUI driver in the FWD client and the javascript code in the browser will communicate freely. The core idea here is that the page is not reloaded or refreshed, but instead the javascript code just handles the rendering of what looks like a terminal and it handles the forwarding of user input (keys in a ChUI environment).
11. The FWD client processes as it normally would except that the ChUI driver delegates the final aspects of the UI to the browser side. Note that, depending on how the FWD application server is configured, the user might be required to enter distinct credentials, to access the application server (which may be different than the OS credentials, which are required to remotely launch the FWD Client).
12. If the user exits the application normally or if it gets automatically disconnected (i.e. due to server shutdown), the browser will be redirected back to the initial login page.

Security¶

TBD: HTTPS only, how our certs work, spawner security, OS accounts for spawning (UNIX/Linux suid bit, Windows OS user auth), session redirect during auth/spawning, one-time auth token and web socket shift, all web resources are from server's jetty (initial auth) or client's jetty (actual web client usage)...

---

© 2004-2020 Golden Code Development Corporation. ALL RIGHTS RESERVED.