Active Directory User Data Adapter

The following article exclusively pertains to a Graylog Enterprise feature or functionality. To learn more about obtaining an Enterprise license, please contact the Graylog Sales team.

This data adapter looks up details about a user account from Active Directory.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

A valid Graylog Enterprise license.

Administrative or read access to Active Directory.

The Graylog server must be able to communicate with the Active Directory domain controllers over the network. This includes verifying firewall rules, network segmentation, and DNS resolution.

Ensure that the Active Directory environment is properly configured and operational. Domain controllers must be reachable from the Graylog server using their IP addresses or hostnames. Additionally, the Active Directory domain name and any necessary authentication details must be available.

Active Directory Prerequisites

The following information is required from Active Directory to set up your data adapter:

LDAP/AD Attributes: Identify the LDAP attributes required for user lookup, such as:
- Unique identifier attribute (e.g. sAMAccountName or userPrincipalName).
- Display name attribute (e.g. displayName).
- Email attribute (e.g. mail or userPrincipalName).
LDAP Search Base and Filter: Determine the LDAP search base and filter to scope the search appropriately within your Active Directory structure:
- Example search base: DC=example,DC=com.
- Example filter: (objectClass=user).

Configure the Data Adapter

You can create a data adapter during the lookup table creation workflow, or they can be created separately on the Data Adapters tab. The following configuration options are available for this data adapter:

Title	A short and unique title for this data adapter.
Description	Data adapter description.
Name	The name used to refer to this data adapter. This should be something unique and recognizable within your Graylog environment.
Custom Error TTL	Time-to-live for custom error messages in seconds.
LDAP Server IP Address	Fully Qualified Domain Name (FQDN) or IP address of LDAP (Active Directory) server.
LDAP Connect Timeout	LDAP connection timeout in milliseconds. It is recommended you leave the default value as is unless it is necessary to modify it.
LDAP Pool Max Connections	The max number of simultaneous connections. It is recommended you leave the default value as is unless it is necessary to modify it.
Base DN	The DN (Distinguished Name) of the LDAP server. This value is commonly in the format of `DC=domainName,DC=tld`. This setting is where the FQDN of the Active Directory domain is `domainName.tld` (TLD meaning top-level domain). If the Active Directory domain has a subdomain, such as `sub.domain.tld`, the example base DN would look like: `DC=sub,DC=domain,DC=tld` This setting controls where Graylog looks up users from. Typically the base DN should be the root of the domain, but you can also set this value to be more granular to exclude values from being returned to Graylog or to optimize lookup performance.
User DN	The DN of the user who is authorized to bind to the LDAP server (e.g. CN=`Administrator`). This user is the account that will perform the Active Directory lookups, so it must have appropriate permissions. (Typically a default user account can read or query all attributes unless customizations have been added to the Active Directory domain.) This value can also be a UPN (universal principal name) (e.g. `user@domain.tld`).
User Password	Password of the above user account.
LDAP Port	The port to bind to the LDAP server: For normal (non-secure, non-encrypted) LDAP: `389` LDAPS: `636`
Enable TLS	Select this checkbox if you wish to enable and configure TLS for AD lookups. This option encrypts data as well as the username/password sent to Active Directory. If not using TLS, the username/password is sent over the network in clear text.
Verify Certificates	Click the checkbox to indicate whether to trust all SSL certificates or verify them against a certificate authority (CA).

Returned Attributes

Returned attributes are the key-value pairs that the data adapter provides as output after a lookup operation.

Attribute	Description
accountExpires	The date when the account expires. This value represents the number of 100-nanosecond intervals since January 1, 1601 (UTC). A value of 0 or 0x7FFFFFFFFFFFFFFF (9223372036854775807) indicates that the account never expires. Example: `9223372036854776000`.
cn (Common Name)	The name that represents an object.
displayName	The display name for an object. This is usually the combination of the users first name, middle initial, and last name.
givenName	Contains the given name (first name) of the user.
memberOf	The distinguished name of the groups to which this object belongs. Graylog parses this as an array. Example: `["CN=groupName,OU=Groups,OU=DomainUsers,DC=domain,DC=local"]`.
primarygroupid	Contains the relative identifier (RID) for the primary group of the user. By default, this is the RID for the Domain Users group.
sAMAccountName	User logon name used to support clients and servers from a previous version of Windows (Pre-Windows 2000).
sn (Surname)	This attribute contains the family or last name for a user.

Example Active Directory Pipeline Rule

This pipeline rule enriches incoming log messages with detailed Active Directory user information.

When a message includes a user_name, it queries the ad-user lookup table, retrieves the user’s AD attributes, and adds them to the message with the prefix ad_user_.

Copy

rule "PARSE AD User Lookup"
when
    has_field("user_name")
then
    let rsAdUser = lookup("ad-user", to_string($message.user_name));
    set_fields(to_map(rsAdUser), "ad_user_");
end

The output may look like as follows:

{

"ad_user_accountExpires": "<Active Directory User Account Expires, in FILETIME>",

"ad_user_cn": "<Active Directory User CN>",

"ad_user_displayName": "<Active Directory User Display Name>",

"ad_user_givenName": "<Active Directory User Given Name>",

"ad_user_memberOf": "<Comma Separated List of Active Directory User Groups>",

"ad_user_primarygroupid": "<Active Directory User Primary Group ID>",

"ad_user_sAMAccountName": "<Active Directory User sAMAccountName>",

"ad_user_sn": "<Active Directory User Surname>"