.. meta::
   :description: Guide for ThinLinc Web Access security practices with
                 TLS certificates. This includes notes regarding
                 creating self-signed certificates for testing, and
                 instructions for using them in different browsers.

.. _tlwebaccess_certificates:

Certificates
~~~~~~~~~~~~

For best security and user experience, we strongly recommend that you
use valid TLS certificates. The certificates should match the server
host names. For correct behavior, you should set the parameter
:servconf:`/vsmagent/agent_hostname` on each of the agents in the
ThinLinc cluster.

If you can't obtain a valid TLS certificate but still want to test
ThinLinc Web Access you can use a self-signed certificate. Such a
certificate, created for ``localhost``, is bundled with Web Access. Any
use of self-signed certificates is insecure and most browsers will
display warnings when they are used. Self-signed certificates must be
manually approved.

.. note::

   In Safari, the certificates **must** match the server hostname, while
   other browsers might be content with a warning. Firstly, this means
   that you cannot connect through an IP address. Secondly, you cannot
   use the bundled self-signed certificate. You can create a new
   self-signed certificate using our shipped helper script
   :program:`make-dummy-cert`. OpenSSL is required to be installed for
   this script. Use it like this:

   .. code:: console

          $ sudo /opt/thinlinc/etc/tlwebaccess/make-dummy-cert `hostname --fqdn`

   Manually approving the self-signed certificate requires some
   additional steps in Safari compared to other browsers. On macOS the
   user must expand the browser dialog that complains about the
   certificate and choose to always accept that certificate. If the user
   already dismissed that dialog, then Safari has to be restarted. A
   self-signed certificate must be manually approved for all machines in
   a cluster.

   If you must test a browser on iOS with a self-signed certificate you
   have to add the certificate as a trusted certificate authority on the
   iOS device. Download the certificate on the device and install it in
   :menuselection:`Settings --> General --> Profile`. Then you also have
   to enable the full trust of that root certificate in the
   :guilabel:`Certificate Trust Settings` which can be found at the
   bottom of the :menuselection:`Settings --> General --> About` page.
   See Apple's instructions `here`_. After using Safari to install
   the certificate, you can use Web Access in any browser on iOS.

   .. warning::

      The above steps for iOS are very insecure and are not recommended
      for production systems. iOS does not have a mechanism for ignoring
      bad certificates for a single site. This means that following the
      method above will result in that your device considers the
      certificate as a generally trusted authority. This can in turn
      allow whoever has access to that certificate's private key to
      generate a certificate that falsely appears valid for any site.
      For example, an evil website could appear to have a valid
      certificate for your bank.

.. _here: https://support.apple.com/HT204477