Launching the Client from a Web Page

This feature allows a web server, such as an intranet or a web portal, to initiate a ThinLinc Client connection with a given configuration on behalf of a user.

Requirements

Web Integration requires an Apache HTTP Server, configured for TLS, with the ability to run CGI scripts.

Note

Some Linux distributions distributes their Apache HTTP server with the mod_cgi module disabled. This module is required for Web Integration to work. On Ubuntu systems, it can be enabled by running the a2enmod cgi command and restarting the httpd service.

Note

If Web Integration is used over HTTP, an attacker with access to the network may be able to intercept user passwords. To protect from this happening, Web Integration automatically redirects to a HTTPS connection when HTTP is used.

Installation

The Web Integration feature is not enabled by default in a ThinLinc installation. An installation script, /opt/thinlinc/share/web_integration/install-web-integration, is provided for ease of installation.

$ sudo /opt/thinlinc/share/web_integration/install-web-integration

Note

After installing the Apache HTTP configuration file, make sure to restart the httpd service to load the new configuration.

While the installation script works as-is on most supported platforms, two environment variables grants you more control over where the configuration file is installed. This can be useful if you have an httpd installation at a custom location.

APACHE_CONF_DIR

If your Apache HTTP server has been installed to a non-standard location, set this environment variable to tell the installation script where the configuration directory is located.

If this parameter is unset, the installation script will attempt to find the configuration directory from a list of known locations.

$ sudo env APACHE_CONF_DIR=/usr/local/etc/httpd/conf.d \
    /opt/thinlinc/share/web_integration/install-web-integration

APACHE_CONF_NAME

The default behavior of the installation script is to install the configuration file in the configuration directory with the name thinlinc.conf. If you already have a file with that name in the configuration directory that you wish to keep, set this environment variable to an different name.

$ sudo env APACHE_CONF_NAME=web-integration.conf \
    /opt/thinlinc/share/web_integration/install-web-integration

Usage

The process works like this:

1. The CGI script is called with the desired parameters.

2. The CGI script generates a “launch file”, which is a normal client configuration file. When the browser recieves this file, it launches the locally installed ThinLinc client.

The launch file delivered to the client is generated from the template /opt/thinlinc/etc/tlclient.conf.webtemplate. The CGI script performs some substitutions on this file, before sending it to the client. Currently, the following variables are substituted:

$server_name$

The server name where the CGI script resides.

$login_name$

The user name, specified by the username CGI parameter.

$password$

The password in hexadecimal ASCII notation, specified by the password or hexpassword CGI parameters.

$autologin$

The value of the autologin CGI parameter.

The CGI Script tlclient.cgi

The CGI script tlclient.cgi is used to start the native client, when launched from a web page. It accepts many parameters which affects its operation. These are described below:

server_name

The desired server name.

username

The desired user name. No default.

password

The desired password, in plain text. No default.

hexpassword

The desired password, in hexadecimal ASCII notation. This parameter overrides the password parameter. No default.

redirto

After launching the native client, the browser will redirect to the web page specified by this parameter. Default value: the empty string.

loginsubmit

This boolean parameter specifies if a login should be directly executed, instead of showing a login form. Default value: 0

autologin

This boolean parameter specifies if the native client should automatically connect to the specified server at startup. Default value: 1

start_program_enabled

This boolean parameter specifies if the native client should request that the server starts the session with the command supplied by the client, as indicated by the start_program_command parameter. Default value: 0

start_program_command

This parameter specifies the command to use when starting the session. Default value: "tl-single-app firefox".

displayurl

This boolean parameter can be used for debugging and development purposes. It will display and URL with all submitted parameters, and do nothing else. Default value: 0

shadowing_enabled

This boolean parameter specifies if the native client should activate shadowing. Default value: 0

shadow_name

This parameter specifies the user to shadow. Default value is the empty string.

To make it easier to test various parameters, the HTML file cgitest.html is included, in the same location as tlclient.cgi. It also demonstrates how to create icons on web pages, which launches ThinLinc sessions.