1.4.2. Dashboard Authentication Configuration

The Dashboard has three primary methods for defining who is allowed to use it. These methods can be combined, and each has its own advantages and limitations.

They are:

Additionally, users can be allowed access without providing credentials via anonymous authentication, or through proxy authentication – both of which are features of the Internal User Database.

Anonymous authentication is the default and only available method in evaluation mode.

1.4.2.1. Internal User Database

The Dashboard can perform authentication independently and without any external source of authentication via its configuration database stored in the file dashboard2.db, located in the Dashboard configuration directory. It provides a graphical user management interface that allows administrators to create and delete users and groups, as well as to assign permissions to them. New passwords must meet the Minimum password length (8 characters by default), which is configured on the Authentication > Internal page of the general settings.

Both LDAP / Active Directory and OAuth2 / OpenID Connect (OIDC) based Single Sign-On (SSO) integrate with this database. The LDAP / Active Directory integration acts as an extension that augments internal users with additional properties, whereas the OAuth2 / OpenID Connect (OIDC) based Single Sign-On (SSO) provided users are largely separate from internal users, and integration is mostly limited to assigning permissions.

Anonymous Authentication

Access without authentication requires a designated user stored in the internal user database. All unauthenticated requests are then treated as if they were authenticated as that user.

This option is configured via the dashboard2/AuthenticationMethods/DefaultUser option in the dashboard2.config file; however, users can still explicitly authenticate as a different user.

Proxy Authentication

Proxy authentication integrates the Dashboard with the authentication system of an HTTP proxy server. In this configuration, the proxy handles authentication, while permissions and user properties are read from the internal user database and optionally the LDAP / Active Directory chain.

Configuring proxy auth via HTTP header.
<Node Key="AuthenticationMethods">
    <Binding Key="TrustedUserHttpHeader" Value="X-Remote-User"/>
</Node>

Proxy authentication is configured using the option dashboard2/AuthenticationMethods/TrustedUserHttpHeader. This specifies an HTTP header name that the proxy must set to the user’s Dashboard login name. The Dashboard will then automatically authenticate that user.

Users can still fall back to the internal user database to, for example, authenticate as a Dashboard administrator—provided the proxy does not prevent this.

Caution

Headers can be forged. When using this option, ensure that untrusted users cannot bypass the proxy and that the proxy does not forward the configured header from untrusted sources. Otherwise, malicious users may authenticate as any user.

Caution

The Dashboard API Token feature will likely not work. The same applies to the Dashboard Python API and the IDE Plugins, unless the proxy is specifically configured for this use case. The proxy would need to map Basic HTTP authentication to the configured header and omit it when the request uses another authentication method.

1.4.2.2. LDAP / Active Directory

This authentication source is tightly integrated with the Internal User Database, meaning that attributes and group memberships found in an LDAP directory are used to “augment” the properties of an internal user, who is transparently created in the internal user database upon their first authentication.

Furthermore, when validating password-based credentials, the system first checks the password in the internal user database; if it matches, the password check by the LDAP authenticator(s) is omitted. However, additional attributes will still be queried from the configured LDAP authenticator(s).

LDAP authenticators are configured entirely within the dashboard2.config configuration file located in the Dashboard configuration folder. Its structure looks like this:

Authentication chain configuration in dashboard2.config.
  <Node Key="AuthenticationMethods">
    <Node Key="Enabled">
      <Binding Key="1" Value="External1"/>
      <Binding Key="2" Value="External2"/>
      ...
    </Node>
    <Node Key="Available">
      <Node Key="External1">
        <Binding Key="Type" Value="ActiveDirectory"/>
        ...
      </Node>
      <Node Key="External2">
        <Binding Key="Type" Value="Ldap"/>
        ...
      </Node>
      ...
    </Node>
  </Node>

The configuration consists of two nodes: Available and Enabled. The Available node provides the details for the different authenticators, whereas the Enabled node defines the order of the LDAP authentication chain. Authenticators defined in Available but not listed in Enabled are inactive but can still be tested on the LDAP settings page.

Two LDAP authenticator types are currently available:

LDAP

This is the generic authenticator. While it requires more configuration, it is flexible enough to integrate with most LDAP protocol compatible server implementations.

ActiveDirectory

This authenticator is based on the generic LDAP one but requires significantly fewer configuration options. In many cases, simply enabling it is sufficient. It is preconfigured for straightforward use with an Active Directory server and leverages the fact that your Windows user account is already authenticated with the Active Directory server when the machine is joined to a domain. This authenticator is only available on Windows.

Caution

Ensure that the Dashboard uses secure communication when connecting to an LDAP-compatible server to prevent passwords from being transmitted in clear text (see Securing Communication with other Services).

These authenticators can retrieve full names, email addresses, and memberships in a configurable set of LDAP groups – specifically those granted any permission in the Dashboard. Full names and email addresses can be overridden locally in user management.

The chain defined by the Enabled node can contain any number of authenticators. If it is empty, no LDAP/Active Directory authentication is used. If multiple authenticators are configured, the first one that finds the user is used.

Caution

LDAP/ActiveDirectory users are not automatically deleted from the internal user database when they are deleted from the LDAP/ActiveDirectory server. To prevent these users from accessing the Dashboard (via internal password or Dashboard provided API Tokens) after deletion from your LDAP/ActiveDirectory server, ensure that the Log in permission is only granted to these users via an LDAP group membership.

Authenticator testing

To assist with configuration, the Authentication > LDAP page of the general settings lists all authenticators defined in Available, marking those not listed in Enabled as inactive. Each authenticator includes tabs for Test User Authentication, Search Users, Search Groups, and Query Known Users (see The authenticator test section of the global settings page). Examine the output of these tests to verify that the authenticator is configured as expected. Warnings may provide hints for improving the configuration. If the server presents untrusted certificates, the tests provide an option to trust them via Trust Selected Certificates.

The authenticator test section of the global settings page

The authenticator test section of the global settings page

Test User Authentication

replicates the dashboard login process and can provide insights if a user is unable to log in.

Search Users

replicates the process used when searching for external users while typing.

Search Groups

replicates the process used when searching for external groups while typing.

Query Known Users

replicates the process used in user management or when sending notification emails.

LDAP Configuration Options

The generic LDAP authenticator reads and authenticates Dashboard users from LDAP servers using the LDAP protocol. Because it offers numerous configuration options, setup may be complex and requires expertise in the structure of the organization’s LDAP directory. For Windows domain environments where the Dashboard runs on a domain-joined Windows machine, the ActiveDirectory authenticator is recommended as it is easier to configure.

LDAP configuration example.
<Node Key="Available">
  <Node Key="Ldap_Example">
    <Binding Key="Type" Value="Ldap"/>
    <Node Key="Properties">
      <Binding Key="Url" Value="ldap://localhost:389"/>
      <Binding Key="StartTls" Value="true"/>
      <Binding Key="BindUser"
               Value="cn=admin,ou=users,dc=example,dc=com"/>
      <Binding Key="BindPassword" Value="secret"/>
      <Binding Key="UserSearchBase" Value="CN=Users,DC=Example,DC=Com"/>
      <Binding Key="UserSearchFilter"
               Value="(&amp;(sAMAccountName={0})(objectClass=user))"/>
      <Binding Key="UserIdAttribute" Value="sAMAccountName"/>
      <Binding Key="GroupSearchBase" Value="CN=Users,DC=Example,DC=Com"/>
      <Binding Key="GroupSearchFilter"
               Value="(&amp;(sAMAccountName={0})(objectClass=group))"/>
      <Binding Key="GroupIdAttribute" Value="sAMAccountName"/>
      <Binding Key="MembershipResolutionStrategy"
               Value="MemberOfAttribute"/>
      <Binding Key="MemberOfAttribute" Value="memberOf"/>
    </Node>
  </Node>
</Node>

For a complete list of available options, refer to the commented-out example in the file dashboard2.config (see Section Initial Configuration).

Communication Encryption

To encrypt communication between the Dashboard and the LDAP or Active Directory server, specify a URL beginning with ldaps (adjusting the TCP port accordingly) or set the StartTls binding to true. The LDAP server must support these connections, and the Dashboard server may need to trust the LDAP server’s certificate. Note that StartTls is only compatible with ldap URLs, not ldaps.

BindUser

Most configurations require a BindUser and a BindPassword to authenticate the Dashboard with the directory for querying user information.

User discovery

User discovery is done via LDAP Searches. Therefore, you need to configure UserSearchBase, i.e., a distinguished name where the LDAP Searches shall start from, UserSearchFilter, i.e., the LDAP Filter used for the search, and UserIdAttribute, the attribute determining the login name. As an alternative, user discovery can be done using the configuration key UserGroup, which accepts a list of LDAP users and LDAP groups that all will be reported as members of one single Dashboard group. In this case, users will not be looked up via LDAP searches but rather via traversal of the LDAP using the member-Attribute (configurable via MemberAttribute). The UserGroup option is deprecated since version 7.3.0.

Group resolution

Group resolution is configured via MembershipResolutionStrategy. Available strategies include GroupFilter, UidGroupFilter, MemberOfAttribute, and the deprecated UserGroup. GroupFilter and UidGroupFilter search for a user’s groups using the filter specified in the corresponding option, using the distinguished name or login name, respectively. MemberOfAttribute reads groups from the attribute specified (memberOf by default). UidGroupFilter is not supported by the ActiveDirectory authenticator. Alternatively, group resolution can be disabled by setting the value to None, which assigns a default group membership to all users. Each strategy requires additional configuration; refer to the dashboard2.config template file for details. If MembershipResolutionStrategy is not set, the system defaults to UserGroup (if set), then GroupFilter (if set), and finally MemberOfAttribute. The ActiveDirectory authenticator defaults to GroupFilter instead of MemberOfAttribute in this case.

ActiveDirectory Configuration Options

The ADSI (Active Directory Service Interfaces) authenticator is recommended for Windows domain environments. It requires that the OS user running the Dashboard be a domain user.

ADSI configuration example.
<Node Key="Available">
  <Node Key="Adsi_Example">
    <Binding Key="Type" Value="ActiveDirectory"/>
    <Node Key="Properties">
      <Binding Key="UseSsl" Value="True"/>
      <Binding Key="UserSearchBase" Value="CN=Users,DC=Example,DC=Com"/>
      <Binding Key="GroupSearchBase" Value="CN=Users,DC=Example,DC=Com"/>
    </Node>
  </Node>
</Node>

For a complete list of available options, refer to the commented-out example in dashboard2.config (see Section Initial Configuration).

The UseSsl option ensures that communication with Active Directory is secure, as provided by the underlying Windows API.

Other configuration options are similar to the generic LDAP Authenticator, though most settings should work out-of-the-box, i.e., users and groups should be searchable while typing within the Dashboard.

Working with multiple LDAP / ActiveDirectory authenticators

We recommend using the Active Directory Global Catalog if you need to utilize multiple LDAP/Active Directory servers.

If the Global Catalog is unavailable, you can still use multiple LDAP/Active Directory authenticators and combine their results using one of two strategies.

How to configure the authenticator aggregation type
<Node Key="AuthenticationMethods">
    <Node Key="Enabled">
      ...
    </Node>
    <!-- Requires a restart -->
    <Binding Key="AggregationType" Value="CHAINING"/>
    <Node Key="Available">
      ...
    </Node>
</Node>

How to configure the authenticator aggregation type shows how to configure the aggregation type.

CHAINING:

(Default) Authenticators are queried sequentially in the order [1] defined by the Enabled node. The first authenticator to find or authenticate a user is used to determine all user properties. This strategy assumes that login names are globally unique across all authenticators. Otherwise, user properties may differ between a password login, an administrator’s query of user details, or the non-interactive sending of Erosion Notifications.

MERGING:

(Experimental) All authenticators are queried in parallel, and the results are merged. If a single-value attribute (such as an email address) is provided by multiple authenticators, precedence is determined by the order [1] in the Enabled node. Multi-value attributes, such as group memberships, are merged. For logins, it is sufficient for one authenticator to accept the user’s password. User information (including group memberships) is merged from all authenticators, even those where the password check failed or where the user account is disabled on that server.

1.4.2.3. OAuth2 / OpenID Connect (OIDC) based Single Sign-On (SSO)

This feature is documented in Section OIDC setup.