LDAP/Active Directory
Overview
LDAP/Active directory can be used to authenticate login requests, and optionally to retrieve additional information about accounts, thereafter referred to as LDAP Search.
Configuring authentication
The following attributes are key to configuring LDAP/Active Directory authentication, though some are only optional to set.
Property Name | Required | Description |
|---|---|---|
| Yes | Whether the LDAP/Active Directory feature is enabled. |
| Yes | Whether DCT must automatically create account records for successful authentication attempts using a username that does not match any accounts. If this is disabled, an administrator must create a DCT account with a If this is enabled, any user with valid credentials in the LDAP/Active Directory server can authenticate to DCT, by default with an empty authorization set (i.e. not being able to view any data or perform any action). |
| Yes | The host name or IP address of the LDAP/Active Directory server. |
| Yes | Port of the LDAP/Active Directory server. This is usually 389 for non-SSL, and 636 for SSL. |
| Yes | Whether the connection to the LDAP/Active Directory server must be performed over SSL. It is highly advised to use SSL. Without SSL, communication between DCT and the LDAP/Active server can be intercepted. |
| Yes | The SSL protocol requires the LDAP/Active Directory server to expose a certificate signed by a Certificate Authority (CA) trusted by the JDK which is running DCT. Refer to the dedicated section below to see how to configure an Active Directory/LDAP server of which certificate is not recognized. |
| No | Microsoft Active Directory only: The DNS name of a domain in the same forest as the accounts which login. DCT will append the For example, if the |
| No | If the LDAP server is not Microsoft Active Directory, the For example, if the |
Authentication using defined LDAP principals (new in 2025.1.0.0)
In this mode of operation, DCT accounts must be created before first login, and at the minimum the username and LDAP principal properties must be set. The username corresponds to the value which users will specify in the UI login form (or equivalent API call), while the LDAP principal is unique identifier for the user record in the LDAP/Active Directory server. The LDAP principal is someting called a Distinguished Name (DN).
Example:
cn=Tony,ou=people,dc=example,dc=com.
Microsoft Active Directory allows some shortcuts in the specification of the DN when binding.
Examples:
<domain>\<user logon name>
<user logon name>@<domain>.com
The configuration of a msad_domain_name or username_pattern is relevant when LDAP principal values are set, and instead only the properties marked as required in the above table must be set in the LDAP configuration.
Authentication using username patterns
In this mode of operation, DCT infers the LDAP principal for each account from the username value. Instead of manually setting the LDAP principal value when creating account, either a username_pattern or a msad_domain_name (when using Microsoft Active Directory) must be set in the configuration, in addition to the required attributes from the above table.
When using a username pattern, the value {0} will be substituted with the username from login request.
Example:
If the username is CN={0},CN=Users,DC=company,DC=com, and a user attempts to login with username bob, DCT will send an authentication request to the configured LDAP server with LDAP principal CN=bob,CN=Users,DC=company,DC=com and the password value provided in the login attempt.
When using an MS AD domain name, DCT will combine the username from login attempts with the configured MS AD domain name
Example:
If the msad_domain_name is set to company.co, and a user attempts to login with username bob, DCT will send an authentication request to the configured Active Directory server with LDAP principal bob@company.co and the password value provided in the login attempt.
If auto-create users is enabled, new accounts will be created in DCT when users log in for the first time. When auto-create users is disabled, accounts must be created before first login.
Other attributes (first name, last name, email, ..) in the domain configuration can optionally be set to have DCT fetch the values of those properties upon each login and update DCT accounts with the retrieved values.
Integration via DCT UI or API
The LDAP/Active Directory Integration can be configured both via DCT UI and API. The below image shows an example of how the configuration can be set in the UI as a way to Authenticate users, auto create new users, as well as map group attributes for authorization within the DCT Access Control system.
The following example requests enable LDAP authentication over SSL with an Active Directory server at address activedirectory.company.co using the us.company.co domain:
curl --location --request PUT 'https://<hostname>/v2/management/ldap-config' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: apk <your API key>' \
--data-raw '{
"enabled": true,
"auto_create_users": true,
"hostname": "activedirectory.company.co",
"enable_ssl": true,
"port": 636,
"domains":[{
"msad_domain_name":"us.company.co"
}]
}'Validating authentication
Updating the LDAP/Active Directory configuration does not guarantee that the provided values are correct, as validating those requires a user to authenticate to DCT. This can be achieved with the ldap-config/validate API endpoints, using the credentials valid for the LDAP/Active Directory server. When provided with a username/password combination, the ldap-config/validate API endpoint will authenticate with the LDAP server. If the response status code is 200, the configuration is correct. Otherwise, the response code will be 400, and the response body will provide information to resolve the configuration problems. For example:
curl --location --request POST 'https://<hostname>/v2/management/ldap-config/validate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: apk <your API key>' \
--data-raw '{
"username": "<ldap-username>",
"password": "<ldap-password>"
}'
Because of a defect in version 3.0.0 of DCT, the above request might fail with a response similar to:
search failed for john.doe with search base null' ,search attribute 'null'
This indicates that authentication works, and search (see below) is not configured.
Login
Once the configuration has been updated, accounts can login (via the UI or API) using the same UI form/API endpoint they would be using for the local username/password authentication feature. For example:
curl -k --location --request POST 'https://<hostname>/v2/login' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"username": "<ldap-username>",
"password": "<ldap-password>"
}'When LDAP/Active directory is enabled, DCT first attempts to validate passwords with the LDAP/Active Directory server, and falls back to local password authentication in case of failure. Enabling LDAP/Active directory is thus a non disruptive operation for existing accounts.
In order to force a transition to LDAP/Active Directory only password authentication, the DCT administrator must either update the account records to remove the password, or disable local password authentication entirely.