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.
<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:
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¶
- 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.
<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="(&(sAMAccountName={0})(objectClass=user))"/>
<Binding Key="UserIdAttribute" Value="sAMAccountName"/>
<Binding Key="GroupSearchBase" Value="CN=Users,DC=Example,DC=Com"/>
<Binding Key="GroupSearchFilter"
Value="(&(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 theStartTlsbinding totrue. The LDAP server must support these connections, and the Dashboard server may need to trust the LDAP server’s certificate. Note thatStartTlsis only compatible withldapURLs, notldaps.- BindUser
Most configurations require a
BindUserand aBindPasswordto 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, andUserIdAttribute, the attribute determining the login name. As an alternative, user discovery can be done using the configuration keyUserGroup, 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 themember-Attribute (configurable viaMemberAttribute). TheUserGroupoption is deprecated since version 7.3.0.- Group resolution
Group resolution is configured via
MembershipResolutionStrategy. Available strategies includeGroupFilter,UidGroupFilter,MemberOfAttribute, and the deprecatedUserGroup.GroupFilterandUidGroupFiltersearch for a user’s groups using the filter specified in the corresponding option, using the distinguished name or login name, respectively.MemberOfAttributereads groups from the attribute specified (memberOfby default).UidGroupFilteris not supported by the ActiveDirectory authenticator. Alternatively, group resolution can be disabled by setting the value toNone, which assigns a default group membership to all users. Each strategy requires additional configuration; refer to thedashboard2.configtemplate file for details. IfMembershipResolutionStrategyis not set, the system defaults toUserGroup(if set), thenGroupFilter(if set), and finallyMemberOfAttribute. The ActiveDirectory authenticator defaults toGroupFilterinstead ofMemberOfAttributein 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.
<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.
<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
Enablednode. 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
Enablednode. 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.