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 /webaccess/oidc/<provider>. Each provider requires a separate configuration section.

Add a configuration section for your provider:

[/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 Parameters in /webaccess/oidc/<provider> 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 /webaccess/oidc/<provider>/client_secret_path, the path in this example is /opt/thinlinc/etc/tlwebaccess/client_secret.txt. Paste only the secret value (no labels or formatting), then secure the file:

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

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 /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, 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 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:

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.