.. meta::
   :description: Guide to configuring automated logins to ThinLinc Web Access from outside services.
   :keywords: automated logins, automation, SSO, Single Sign-On, integration

.. _tlwebaccess_automation:

Automation
----------

When configuring automated logins from services outside of ThinLinc Web
Access, it is recommended to use ThinLinc's :ref:`OpenID Connect feature
<authentication_oidc>` which is integrated into Web Access.

For instructions on how to set up this integration, see
:ref:`tlwebaccess_oidc_integrating`.

In scenarios where an OpenID Connect provider is not available,
automated logins in Web Access can be achieved using the legacy method
below.

.. _tlwebaccess_legacy_automation:

Legacy automation
~~~~~~~~~~~~~~~~~

It may be desirable to automatically log users into ThinLinc Web Access
from a non-ThinLinc service such as a web portal or an intranet page
when OpenID Connect is not available. In such cases it is possible to
replicate the behavior of the login page, where users normally input
their username and password.

If Web Access has been configured to only require password
authentication, it is sufficient to send a ``POST`` request to the
login page with parameters consistent with the form below:

.. code:: html

   <form method="post" action="https://tl.example.com:300/">
      <input type="hidden" name="username" value="<username>">
      <input type="hidden" name="password" value="<password>">
      <input type="submit" value="Login">
   </form>

On systems where Web Access has been configured through PAM to request
further information from the user, such as when 2FA is enabled, it is
possible to provide additional authentication parameters as well.

This allows logins to be fully automated even in situations where users
would normally be required to input a password and for example an
:ref:`OTP <otp_authentication>`. Such as if the OTP is provided by the
web portal itself.

When logging in, the password prompt is always the first input. Prompts
subsequent to the password can be added via numbered parameters. These
need to be named following the naming format ``prompt_<N>``. The
number ``N`` needs to be a non-negative integer, and is used to
determine the order in which the parameters are processed.

Extending the previous example to also contain an OTP, the form will
look like the following:

.. code:: html

   <form method="post" action="https://tl.example.com:300/">
      <input type="hidden" name="username" value="<username>">
      <input type="hidden" name="password" value="<password>">
      <input type="hidden" name="prompt_2" value="<OTP>">
      <input type="submit" value="Login">
   </form>

Ordering of parameters
^^^^^^^^^^^^^^^^^^^^^^

Given multiple additional prompt steps where some still require
interaction from the user, it is necessary that all automated steps
occur first.

The values of ``N`` are only used to determine the order in which
the first few prompt parameters are processed.

Handling of messages
^^^^^^^^^^^^^^^^^^^^

Web Access is able to pass on messages while the user is logging in. If
a message is encountered before all prompt values have been consumed,
the message will be returned to the user and any unused prompt values
will be dropped, ending the automation early.

If it is a requirement to show messages during an automated login, these
need to be configured to be shown after the automated steps.