.. meta::
   :description: Guide to configuring ThinLinc for one-time password
                 (OTP) authentication, including integration with
                 external OTP servers for enhanced security.

.. _otp_authentication:

One-time passwords
------------------

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

One-time passwords (OTPs) can be used as a mechanism for authenticating users
with ThinLinc, as a second factor together with other mechanisms such as
a standard password. This technique is known as two-factor
authentication (2FA).

In this section, we give an overview of the general requirements for
using OTPs with ThinLinc, and how they work in practice. For
configuration with specific OTP providers, please refer to the relevant
third-party documentation.

General requirements
~~~~~~~~~~~~~~~~~~~~

-  An OTP provider which accepts the OTP twice. This is due to the
   ThinLinc architecture: the client authenticates first with the master
   server and then with the agent, using the same OTP.

-  A PAM module capable of communicating with your OTP provider.
   Depending on the protocol being used, you may require a
   provider-specific module, or be able to use a generic one such as
   :file:`pam_radius_auth` from the FreeRADIUS project.

-  The SSH server on the ThinLinc servers must accept
   "keyboard-interactive" authentication. It is recommended to disable
   "password" authentication when using OTPs.

Configuration
~~~~~~~~~~~~~

As ThinLinc relies on the server operating system to handle user
authentication, there is no ThinLinc-specific configuration required in
order to use OTPs. However, you will need to configure PAM and SSH on
all ThinLinc servers which require an OTP for user authentication. There
may also be some provider-specific configuration required.

SSH configuration
^^^^^^^^^^^^^^^^^

The SSH server must provide "keyboard-interactive" as an authentication
method when using OTPs with ThinLinc. In OpenSSH, this is achieved by
using the "KbdInteractiveAuthentication" parameter:

.. code:: console

   KbdInteractiveAuthentication yes

Disabling the "password" authentication method can be done using the
"PasswordAuthentication" parameter:

.. code:: console

   PasswordAuthentication no

Note that this setting does not prevent normal passwords from being
used, either on their own or in combination with an OTP.

SSH must be configured to use PAM for authentication. This is the
default on most Linux distributions, but you can specify PAM
authentication explicitly by providing the "UsePAM" parameter:

.. code:: console

   UsePAM yes

PAM configuration
^^^^^^^^^^^^^^^^^

PAM must be configured to require an OTP for user authentication. To do
this, a PAM module capable of communicating with your OTP provider must
be installed.

.. note::

   Because the PAM stack differs between systems and distributions, the
   following information is of a general nature only. For further
   details regarding PAM configuration, please refer to the relevant PAM
   and/or distribution-specific documentation.

To enable the module in PAM, add a corresponding rule to the relevant
configuration file, normally found under :file:`/etc/pam.d/`. The order
is important, and the correct location for the rule will depend on your
existing PAM stack.

You will generally want to insert a line like the following, where
:file:`module_name` is the name of the module being used to communicate
with your OTP provider:

.. code:: console

   auth         required        module_name.so

Depending on the module being used, there may be additional parameters
which can be specified here. For example, it may be possible to
configure the prompt shown to users when entering the OTP. For further
information on these parameters, refer to the PAM module documentation.

For general information on how PAM is used in ThinLinc, see
:ref:`authentication_pam`.

Provider-specific configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In addition to the steps outlined above, there may also be some
provider-specific configuration to perform prior to using the OTP
service for authentication. This may include passing parameters directly
to the PAM module, creating or modifying a configuration file, or
running an installation script. As these steps will differ between
providers, please see the relevant third-party documentation for
details.
