.. _clientplatforms_web_integration:

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.

.. _clientplatforms_web_integration_requirements:

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 :command:`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.

.. _clientplatforms_web_integration_installation:

Installation
~~~~~~~~~~~~

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

.. code:: console

   $ 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.

.. environ:: 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.

   .. code:: console

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

.. environ:: APACHE_CONF_NAME

   The default behavior of the installation script is to install the
   configuration file in the configuration directory with the name
   :file:`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.

   .. code:: console

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

.. _clientplatforms_web_integration_usage:

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
:file:`/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.

.. _clientplatforms_tlclient_cgi:

The CGI Script tlclient.cgi
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The CGI script :file:`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
:file:`cgitest.html` is included, in the same location as
:file:`tlclient.cgi`. It also demonstrates how to create icons on web
pages, which launches ThinLinc sessions.