.. meta::
   :description: Guide to configuring ThinLinc for single sign-on (SSO)
                 authentication, and an overview of related commands.

.. _sso_authentication:

Single sign-on
--------------

Introduction
~~~~~~~~~~~~

Single sign-on (SSO) is a method for performing multiple authentications
using the same credentials, while only having to enter them once. For
example, SSO may be used when launching an application within your
ThinLinc session which requires the same password as the one already
entered in the ThinLinc client.

Overview
~~~~~~~~

When authenticating with ThinLinc, the encrypted PIN or password is
stored securely as one of the session properties. This allows it to be
retrieved later, using a key which is only available within the ThinLinc
session. To disable storage of the PIN or password, set the
:servconf:`/vsmagent/single_signon` parameter to :option:`0` on the
agent server.

ThinLinc provides a number of tools for retrieving, updating, and
removing the encrypted password or PIN. These tools and their usage are
described in the sections below.

Password-based SSO
~~~~~~~~~~~~~~~~~~

The :program:`tl-sso-password` command can be used within a ThinLinc
session to retrieve or remove the stored password. This command is
intended to be used in combination with other programs, rather than on
its own — for example, by piping the output into a program which accepts
a password on standard input.

This allows :program:`tl-sso-password` to be used as part of a custom
command to launch a program requiring authentication, without needing to
prompt the user for their password again. For example, this could be
done by creating a desktop application using :ref:`tldc`.

For more information on usage, see :doc:`man/tl-sso-password.1`

Updating the SSO password
^^^^^^^^^^^^^^^^^^^^^^^^^

In some situations it may be necessary to prompt the user for an SSO
password, for example when the password entered in the ThinLinc client
is different to the one being used within the session itself. To help
with this, the command :program:`tl-sso-update-password` is provided.

Running this command will present a dialogue to the user prompting them
to enter a new password, after which the password stored inside the
ThinLinc session will be updated.

To configure ThinLinc so that :program:`tl-sso-update-password` is run
during login, create a symlink as follows:

.. code:: console

   sudo ln -s /opt/thinlinc/bin/tl-sso-update-password \
        /opt/thinlinc/etc/xstartup.d/05-tl-sso-update-password

Token-based SSO
~~~~~~~~~~~~~~~

Some authentication methods do not require a password. For example,
smart cards often use a PIN. When using these forms of authentication,
ThinLinc provides the :program:`tl-sso-token-passphrase` command for
retrieving the PIN (or "token") entered when connecting with the
ThinLinc client. This command is identical to the
:program:`tl-sso-password` command outlined above, except that it
operates on the token rather than the password. 

When using smart card authentication, :program:`tl-sso-token-passphrase`
is used in a similar way to :program:`tl-sso-password` for providing
single sign-on with applications which require the same credentials. In
this case, make sure to select ":guilabel:`Send smart card passphrase
(PIN) to server`" in the ":guilabel:`Security`" tab of the ThinLinc
client options, and ensure smart card readers are exported in the
":guilabel:`Local devices`" tab.