.. meta::
   :description: Guide to configuring ThinLinc Web Access for a OIDC
                 provider. Includes configuration structure and guides
                 on the most important parameters.

.. _oidc_config:

Configuration
-------------

This section describes how to set up Web Access to enable authentication
via OIDC.

Adding an OIDC provider
~~~~~~~~~~~~~~~~~~~~~~~

OIDC providers for Web Access are configured in
:servconf:`/webaccess/oidc/\<provider\>`. Each provider requires a
separate configuration section.

Add a configuration section for your provider:

.. code:: ini

   [/webaccess/oidc/<provider>]
   username_claim=example-claim
   discovery_url=https://idp.example.com/.well-known/openid-configuration
   client_id=your-client-id
   client_secret_path=/opt/thinlinc/etc/tlwebaccess/client_secret.txt

Replace ``<provider>`` with a unique identifier for your provider
(e.g., ``entra``, ``keycloak``).

See :ref:`configuration_tlwebaccess_oidc` for detailed parameter
descriptions.

Storing the client secret
~~~~~~~~~~~~~~~~~~~~~~~~~

The client secret must be stored in a separate file with restricted
permissions. The file path is specified in
:servconf:`/webaccess/oidc/<provider>/client_secret_path`, the path in
this example is :file:`/opt/thinlinc/etc/tlwebaccess/client_secret.txt`.
Paste only the secret value (no labels or formatting), then secure the
file:

.. code:: console

   $ sudo chown root:root /opt/thinlinc/etc/tlwebaccess/client_secret.txt
   $ sudo chmod 600 /opt/thinlinc/etc/tlwebaccess/client_secret.txt

.. _authentication_oidc_username_mapping:

Username mapping
~~~~~~~~~~~~~~~~

Claims are issued by the provider for authenticated users. These can be
used to map the user to a Linux user account. The paramater
:servconf:`/webaccess/oidc/<provider>/username_claim` specifies which
claim contains the username. The claim value must be reliable, unique,
and match a Linux username exactly (or an alias resolvable by, for
example, :command:`getent`).

There is no universal username claim that works for all providers. Some
providers allow admins to configure custom claims. Be cautious of using
``preferred_username`` as it can be freely modified by the end-user in
some systems. Consult your provider's documentation for details.

It is crucial to correctly configure the username claim. Ensure that the
following requirements are met for the selected claim:

- The value is admin-controlled and can't be modified by an end-user
- The value matches the correct Linux username or an alias of it
- The value is unique and reliably identifies the user without conflicts
- The claim is issued by the provider (depends on selected scopes, as
  explained in :ref:`authentication_oidc_scopes`)

.. warning::

   The **username_claim** is security-critical and incorrect use can
   result in unauthorized access. Ensure the above requirements are met
   before proceeding.

Consult your provider's documentation for the available claims and which
ones meet the above requirements.

In Microsoft Entra ID, for example, if the claims contain
``{"samaccountname": "john.smith"}`` and the Linux user is
``john.smith``, configure:

.. code:: ini

   username_claim=samaccountname

.. note::

   Note that uniqueness of the ``username_claim`` claim often can't be
   guaranteed in multi-tenant environments.

Remember to restart your ThinLinc services before you attempt to sign in
using OIDC.
Check the logs for any configuration errors.