Configuring LDAP and Active Directory Authentication

Summary

This tutorial explains how to configure external authentication sources in Chariot using Microsoft Active Directory and LDAP. You will learn how to create authentication sources, configure bind methods, authenticate Chariot UI and REST API users against external directory services, and map directory users and groups to Chariot roles.

LDAP (Lightweight Directory Access Protocol) is a standard protocol used to access and manage directory services such as user accounts, groups, and authentication information. Microsoft Active Directory is built on LDAP and provides additional identity and domain management features for Windows environments. Both authentication methods use simple bind authentication to connect to the external directory and validate user credentials.

⚠️ This feature is available in Chariot v2.4.2 and newer.

---

Microsoft Active Directory Authentication

The Active Directory authentication source allows Chariot to authenticate users against a Microsoft Active Directory server and determine group membership for Chariot role mapping.

Chariot supports two authentication methods for Active Directory sources:

• Bind with Login/Username
• Bind with Distinguished Name (DN)

Bind with Login/Username

This is the default authentication method. When a user logs in, Chariot appends a configured domain suffix to the username before sending the bind request to Active Directory. Optional username prefixes and suffixes can also be configured manually.

Example

If the following configuration is used:

• Domain: example.com
• Auto Suffix: Enabled

then,

• A user logging in with the username: jdoe
• Would authenticate using: jdoe@example.com

Configure an Active Directory Source

1. Navigate to: Accounts → Sources under the Configuration menu.
2. Select Add Source.
3. Choose Active Directory as the source type.
4. Enter the Active Directory configuration values.
5. Select Add to save the source.

Bind with Distinguished Name (DN)

This method searches Active Directory for the user's Distinguished Name (DN) before performing authentication. Instead of appending a domain suffix, Chariot searches for a user entry that matches the configured search criteria. If a matching user is found, the DN of that entry is used for the bind request.

Required Configuration for this method:

• Domain must be left empty
• Auto Suffix must be disabled
• Username Prefix must be empty
• Username Suffix must be empty

Chariot uses the following fields to locate the user:

• User Search Base
• User Search Filter
• User Name Attribute

Example configuration:

• User Search Base: CN=Users,DC=example,DC=com
• User Search Filter: (&(objectClass=user)(sAMAccountName={0}))
• User Name Attribute: sAMAccountName

If the user jdoe is found, Chariot may authenticate using the DN:

CN=John Doe,CN=Users,DC=example,DC=com

Configure an Active Directory Source Using DN Binding

1. Navigate to: Accounts → Sources under the Configuration menu.
2. Select Add Source.
3. Choose Active Directory as the source type.
4. Expand the Advanced Options section.
5. Enter the required search and bind configuration values.
6. Select Add to save the source.

7. Click on the newly created Source entry to inspect the Configuration, Users, and Roles in MyActiveDirectory.

---

LDAP Authentication

The LDAP authentication source allows Chariot to authenticate users against a generic LDAP directory server.

When a user logs in, Chariot maps the supplied username to the Distinguished Name (DN) of an LDAP entry using the configured LDAP template. Chariot then performs simple bind authentication and evaluates group membership to determine the appropriate Chariot role assignments.

Configure an LDAP Source

1. Navigate to: Accounts → Sources under the Configuration menu.
2. Select Add Source.
3. Choose LDAP as the source type.
4. Enter the LDAP configuration values. Reference tables are below.
5. Select Add to save the source.
6. Select the newly created source to review:
   • Configuration
   • Users
   • Roles

MQTT Client Authentication with LDAP

This section explains how to configure Chariot to authenticate and authorize MQTT clients using an LDAP server instead of local MQTT credentials.

Requirements

• LDAP entries used for authentication must support simple bind requests
• LDAP entries used for authorization must extend the cls-mqttCredential object class
• ACL permissions are configured using:
  • cls-subTopicFilter
  • cls-pubTopicFilter

⚠️ This feature is available in Chariot v2.4.2 and newer.

LDAP Schema Files

Sample LDAP schema and LDIF files are available in samples/ldap/ldif/

MQTT LDAP Object Classes

cls-mqttCredential

Property	Value
OID	1.3.6.1.4.1.60051.2.2.1
Type	Auxiliary

This object class represents ACLs associated with an MQTT client. It may include one or more of the following attributes:

• cls-subTopicFilter
• cls-pubTopicFilter

MQTT LDAP Attributes

cls-subTopicFilter: Defines an MQTT topic filter the client is permitted to subscribe to.

Property	Value
OID	1.3.6.1.4.1.60051.2.1.1

cls-pubTopicFilter: Defines an MQTT topic filter the client is permitted to publish to.

Property	Value
OID	1.3.6.1.4.1.60051.2.1.2

Configure MQTT LDAP Authentication

1. Navigate to: MQTT Credentials under the Configuration menu.
2. Select the LDAP tab.
3. Enter the LDAP server configuration values. Reference tables are below.
4. Save the configuration.

Configuration Reference Tables

Microsoft Active Directory

Property	Required	Description	Default
Name	X	A unique name for this source configuration
Enabled		A boolean indicating if the LDAP Realm should be enabled	true
Host	X	The IP address or hostname of the directory server
Port	X	The port number of the directory server	389
Use TLS		Whether to use a TLS encrypted connection	false
System Username	X	The Distinguished Name (DN) used to authenticate with the directory server
System Password	X	The password used to authenticate with the directory server
Domain		The Windows Active Directory domain name. Example: "MyDomain.com".
Auto Suffix		If Chariot should automatically append "@<domain>" to the username when authenticating	true
System Suffix/Prefix		If the Auto Suffix and/or Username Suffix/Prefix setting should also be applied to the System Username	true
Username Suffix		A manually specified suffix to append to the username when authenticating
Username Prefix		A manually specified prefix to prepend to the username when authenticating
User Search Base	X	The base Distinguished Name (DN) for searching for users in the directory server Multiple DNs can be listed by surrounding each one with parenthesis
User Search Filter		The search filter for querying a user	(&(objectClass=user)(sAMAccountName={0}))
User List Filter		The search filter for listing users	(&(objectClass=user)(sAMAccountName=*))
User Name Attribute		The directory server attribute that represents the login username of the user	sAMAccountName
User Full Name Attributes		The directory server attribute that represents the full name of the user	name
User Group Attribute		The directory server attribute that represents the groups of a user	memberOf
Group Search Base	X	The base Distinguished Name (DN) for searching for groups in the directory server Multiple DNs can be listed by surrounding each one with parenthesis
Group Search Filter		The search filter for querying groups in the directory server	(objectClass=group)
Group Name Attribute		The directory server attribute that represents the group name	cn
Group To Role Mapping	X	A comma separated mapping of directory server group names to Chariot role names
Referral		How Chariot should handle referrals returned by the directory server ('ignore' or 'follow')	ignore
Connect Timeout		The maximum time in milliseconds that Chariot will attempt a connection to the directory server	10000
Read Timeout		The maximum time in milliseconds that Chariot will attempt a read with the directory server	5000
Enable Cache		Whether results from the directory serve should be cached locally	true
Cache Timeout		The period of time cached results will be held before needing to be updated	10000

LDAP

Property	Required	Description	Default
Name	X	A unique name for this source configuration
Enabled		A boolean indicating if the LDAP Realm should be enabled	true
Host	X	The IP address or hostname of the directory server
Port	X	The port number of the directory server	389
Use TLS		Whether to use a TLS encrypted connection	false
System Username	X	The Distinguished Name (DN) used to authenticate with the directory server
System Password	X	The password used to authenticate with the directory server
User Search Base	X	The base Distinguished Name (DN) for searching for users in the directory server Multiple DNs can be listed by surrounding each one with parenthesis. ou=users,dc=example,dc=com
User DN Template	X	The template for building the user's Distinguished Name (DN)	uid={0},ou=users,dc=example,dc=com
User List Filter		The search filter for listing users	(&(objectClass=inetOrgPerson)(uid=*))
User Name Attribute		The directory server attribute that represents the short name of the user	uid
User Full Name Attributes		The directory server attribute that represents the full name of the user	cn
Group Search Base	X	The base Distinguished Name (DN) for searching for groups in the directory server Multiple DNs can be listed by surrounding each one with parenthesis. ou=groups,dc=example,dc=com
Group Search Filter		The search filter for querying groups in the directory server	(objectClass=groupOfNames)
Group Name Attribute		The directory server attribute that represents the group name	cn
Group To Role Mapping	X	A comma separated mapping of directory server group names to Chariot role names
Referral		How Chariot should handle referrals returned by the directory server ('ignore' or 'follow')	ignore
Connect Timeout		The maximum time in milliseconds that Chariot will attempt a connection to the directory server	10000
Read Timeout		The maximum time in milliseconds that Chariot will attempt a read with the directory server	5000
Enable Cache		Whether results from the directory serve should be cached locally	true
Cache Timeout		The period of time cached results will be held before needing to be updated	10000