.. meta::
   :description: Overview of configuration parameters for the ThinLinc
                 Web Access client, including TLS encryption settings,
                 login page redirection, and logging configuration.

.. _configuration_tlwebaccess:

.. server-config-folder:: /webaccess

Parameters in /webaccess/
~~~~~~~~~~~~~~~~~~~~~~~~~

In this section, we will describe all the parameters currently used by
the ThinLinc Web Access client. These configuration parameters reside
in :file:`/opt/thinlinc/etc/conf.d/webaccess.hconf`.

.. server-config:: /webaccess/cert

   The path to the certificate file to be used for TLS encryption.

   .. note::

      This certificate may be downloaded by connecting clients to be
      installed in their browsers. Make sure that this file does not
      contain a private key.

.. server-config:: /webaccess/certkey

   The path to the certificate private key file used for TLS encryption.

.. server-config:: /webaccess/gnutls_priority

   The GnuTLS priority string is used to select the order and
   availability of TLS versions, ciphers, key exchange, MAC,
   compression, signature and elliptic curve algorithms for TLS
   sessions. See :ref:`gnutls-priorities` for possible values.

.. server-config:: /webaccess/logging/logfile

   The file to use for logging tlwebaccess messages. By default, this is
   :file:`/var/log/tlwebaccess.log`.

.. server-config-folder:: /webaccess/login

.. server-config:: /webaccess/login/password

   Allow logging in using traditional username and password. Enabled by
   default. If disabled, only OIDC login is available.

.. server-config:: /webaccess/login_page

   The URL which is used to redirect back to the Web Access login page
   on the master server. The default value is ``/``, which redirects to
   the current server. This parameter needs to be changed when ThinLinc
   Web Access is used in a cluster setup.

.. server-config:: /webaccess/listen_port

   The local port for this service to listen on. The default port used
   is ``300``.

.. server-config:: /webaccess/server_tokens

   If set to ``true``, Web Access includes the ThinLinc version,
   as well as Python version information in the "Server" response header
   field. If set to ``false``, the "Server" response header will not
   include any version information. The default value is ``true``.

   .. note::

      Disabling server_tokens might make it easier to work with some
      security scanners that raise alerts when this type of version
      information is included. But note that hiding version information
      does nothing to make your server more secure.

.. server-config:: /webaccess/trusted_proxies

   A space-separated list of proxies that should be considered trusted when
   handling the ``X-Forwarded-For`` HTTP header. Each entry in the list needs
   to be a valid IP address in either IPv4 or IPv6 format.

   For more information on how this feature works and important security
   implications, see :ref:`forwarding_client_ip`.

.. _configuration_tlwebaccess_branding:

.. server-config-folder:: /webaccess/branding

Parameters in /webaccess/branding/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This section describes the parameters used for customizing the Web
Access login page. Read more in :ref:`tlwebaccess_branding`.

.. server-config:: /webaccess/branding/background

   The path to a background image to be displayed on the Web Access
   login page. Any path on the local filesystem works. This background
   will appear only on large screens, surrounding the central box on
   the login page.

   The background image will be stretched to cover the entire page. A
   semi-transparent white overlay will be applied on top of the
   background. The image formats SVG, PNG, JPEG, GIF, and WEBP are
   supported. The file must be readable by a non-privileged user. No
   background image is used by default.

.. server-config:: /webaccess/branding/logo

   The path to the logo to be displayed on the Web Access login page.
   Any path on the local filesystem works. If this logo used, it will be
   displayed in place of the ThinLinc logo. A smaller variant of the
   ThinLinc logo will then appear below the login button.

   Maximum displayed width and height is 360 px, it will be scaled down
   if larger. It is recommended to pick a logo that fits well on a white
   background. The image formats SVG, PNG, JPEG, GIF, and WEBP are
   supported. The file must be readable by a non-privileged user. Only
   the ThinLinc logo is used by default.

.. server-config:: /webaccess/branding/title

   A short string to be displayed in the browser window or tab title.
   This is empty by default.

.. _configuration_tlwebaccess_hsts:

.. server-config-folder:: /webaccess/hsts

Parameters in /webaccess/hsts/
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This section describes the parameters used for HSTS in Web Access. Read
more in :ref:`configuring_hsts_header`.

.. server-config:: /webaccess/hsts/allow_browser_preload

   *Requirements:* ``policy=permanent`` and ``subdomains_included=true``

   With ``allow_browser_preload`` enabled, it is indicated to the
   browser that the intention is to add the domain, and subdomains, to
   the browsers’ lists. This would result in the HSTS policy being
   enabled at the first visit to the domain or subdomain.

   .. note::

      Only use this option if you are sure to support HTTPS for domains
      and subdomains. It may be difficult to remove domains and
      subdomains from the preload list.

.. server-config:: /webaccess/hsts/policy

   Note the warnings about enabling HSTS policy, see
   :ref:`configuring_hsts_header`. The results should be considered
   permanent once enabled and are difficult to reverse. The only way to
   disable the HSTS policy is to wait for the specified duration, as
   described below, to pass until visiting the domain again.

   - ``Off``: The default value. The HSTS header will not be sent.
   - ``Testing``: Before setting the policy to permanent, it is
     recommended to test if the policy works for the intended domains to
     verify they support HTTPS. This value indicates to the browser that
     it should only remember this domain for 10 minutes.
   - ``Permanent``: This value indicates that browsers will remember
     this domain for 2 years. This duration is refreshed every time a
     domain is revisited, which is why it should be viewed as permanent.

.. server-config:: /webaccess/hsts/subdomains_included

   The HSTS policy will be applied to the included subdomains of the
   ThinLinc host if enabled.

   .. note::

      It is recommended to verify that all subdomains support HTTPS
      before enabling this. In order to verify, set ``policy=testing``,
      restart the service and  then visit Web Access in the browser to
      enable the HSTS policy.

.. _configuration_tlwebaccess_oidc:

.. server-config-folder:: /webaccess/oidc/<provider>

Parameters in /webaccess/oidc/<provider>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

OpenID Connect (OIDC) providers are configured in separate sections
identified by ``<provider>``. Each section configures one provider. See
:ref:`authentication_oidc` for setup instructions and examples.

The following four parameters  are required for OIDC authentication to function:

- :servconf:`username_claim </webaccess/oidc/<provider>/username_claim>`
- :servconf:`discovery_url </webaccess/oidc/<provider>/discovery_url>`
- :servconf:`client_id </webaccess/oidc/<provider>/client_id>`
- :servconf:`client_secret_path </webaccess/oidc/<provider>/client_secret_path>`

All other parameters are optional and have sensible defaults. Detailed
parameter descriptions are provided below.

.. server-config:: /webaccess/oidc/<provider>/button_text

   Optional parameter for setting custom text for the login button
   displayed on the Web Access login page. If not set, the button text
   defaults to :guilabel:`<provider>`, which is the identifier specified
   in the configuration section name.

.. server-config:: /webaccess/oidc/<provider>/client_id

   Specifies the client identifier assigned by the provider. The client
   ID is obtained during application registration at the provider.

   This parameter is required and has no default value.

.. server-config:: /webaccess/oidc/<provider>/client_secret_path

   Specifies the path to a file containing the client secret. The file must
   contain only the secret value with no labels, comments, or additional
   formatting. The file must not be readable or writable by others than
   the file owner.

   This parameter is required and has no default value.

.. server-config:: /webaccess/oidc/<provider>/discovery_url

   Specifies the OIDC discovery endpoint URL. The discovery URL provides
   the OIDC provider metadata. ThinLinc automatically retrieves endpoint
   URLs and signing keys from this URL. The URL must end with
   ``/.well-known/openid-configuration``.

   This parameter is required and has no default value.

.. server-config:: /webaccess/oidc/<provider>/icon_path

   Optional parameter for setting the path to a custom icon for the
   login button. We recommend using SVG files, but if not, the icon
   should be at least 20×20. The image formats SVG, PNG, JPEG, GIF, and
   WEBP are supported. The file must be readable by a non-privileged
   user. No icon is displayed by default.

.. server-config:: /webaccess/oidc/<provider>/prompt

   Optional parameter that controls authentication prompts shown at the
   provider.

   **Possible values:**

   - ``none`` - Silent authentication (no prompts)
   - ``login`` - Always prompt for credentials
   - ``consent`` - Show consent screen
   - ``select_account`` - Show account selection interface

   No prompt parameter is set by default, this leaves the behavior up to
   the provider. For details on prompt parameter behavior, refer to
   `OpenID Connect Core 1.0 - Authentication Request
   <https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest>`__.

   .. note::

      When set to ``none``, silent authentication only succeeds if the
      user has an existing session at the provider. The ``consent``
      value prompts for user consent on the first login, then subsequent
      logins follow silent authentication if consent has been granted.

.. server-config:: /webaccess/oidc/<provider>/scope

   Optional parameter for additional OAuth 2.0 scopes to be requested
   from the provider. The ``openid`` scope is always requested from the
   provider, the scopes specified here are requested in addition to it.
   The scopes control which claims are included. The value is a
   space-separated list of additional scope identifiers. Consult your
   provider’s documentation for available scopes.

.. server-config:: /webaccess/oidc/<provider>/username_claim

   The claim that contains the username. The value of this claim must be
   reliable, unique and match a Linux username on the ThinLinc server
   exactly. There is no universal username claim that works for all
   providers. See :ref:`authentication_oidc_username_mapping` for
   requirements and tips on how to approach this.

   This parameter is required and has no default value.
