LdapClient

Introduction

The LdapClient module manages connections and access to LDAP directory services.

Each module instance manages a connection pool for one logical directory destination. A destination can contain several equivalent servers for failover. Configure separate named module instances for unrelated directories, or increase the number of instances to raise throughput.

The module provides an internal event-bus service with a JSON-based protocol and a Java library for simplified use.

This module is used for all internal LDAP access, including the bundled LDAP valves.

Configuration

Note

Module name: LdapClient | LDAPClient

Properties

Name	Description	Default	Mandatory
name	Destination name. Unique identifier for a specific configuration/connection/service. This value must be unique for all ldapclient configurations.	"default"
instances	Number of instances to deploy.	1
connection	LDAP connection configuration.	{}

Example

{
  "name": "LdapClient",
  "instances": 1,
  "config": {
    "name" : "default",
    "connection" : {
      "host" : "127.0.0.1",
      "port" : 389,
      "bind_dn" : "cn=Directory Manager",
      "bind_password" : "password",
      "use_ssl" : false
    }
  }
}

Connection

Properties

Name	Description	Default	Mandatory
host	Hostname or Ip-address to LDAP directory service. (Mandatory unless hosts is used)
port	LDAP server port used with host and as the default for hosts entries that omit a port.	636 with SSL; otherwise 389
hosts	List of LDAP directory service hosts:ports. If more than one is specified, fail-over is enabled. When this property is used, host and port properties are optional.
bind_dn	DN of the account used to authenticate the connection pool.	""
bind_password	Password of the account used to authenticate the connection pool.	""
pool_min_connections	Minimum number of pooled LDAP connections. Must be at least 1.	1
pool_max_connections	Maximum number of pooled LDAP connections. Must not be lower than pool_min_connections.	16
connect_timeout_ms	Specifies the maximum length of time in milliseconds that a connection attempt should be allowed to continue before giving up. A value of zero indicates that there should be no connect timeout.	10000
response_timeout_ms	Specifies the maximum length of time in milliseconds that an operation should be allowed to block while waiting for a response from the server. A value of zero indicates that there should be no timeout.	2000
abandon_on_timeout	Specifies whether the LDAP client should attempt to abandon any request for which no response is received in the maximum response timeout period.	true
follow_referrals	Specifies whether associated connections should attempt to follow any referrals that they encounter, using the referral connector for the associated connection.	false
use_keep_alive	Specifies whether to use the SO_KEEPALIVE option for the underlying sockets used by associated connections.	false
use_linger	Specifies whether to use the SO_LINGER option for the underlying sockets used by associated connections.	false
linger_timeout_secs	SO_LINGER timeout in seconds.	30
use_schema	Specifies whether to try to use schema information when reading data from the server (e.g., to select the appropriate matching rules for the attributes included in a search result entry).	false
use_ssl	Specifies if SSL/TLS should be used or not.	true
ssl_trust_all	Turns on/off trust validation for SSL/TLS connections.	false
ssl_truststore_path	Path to custom SSL truststore. If not specified, the default Java truststore will be used.
ssl_truststore_password	Custom truststore password
ssl_truststore_type	Truststore type used for the custom truststore.	"JKS"
ssl_truststore_validate_time	Turns on/off peer certificate validity check.	true
is_active_directory	Turns on/off Active Directory specific paginated search results.	true

Example

{
  "connection" : {
   "host" : "127.0.0.1",
   "port" : 389,
   "hosts" : "fail-over-host-01:389,fail-over-host-02:1389",
   "bind_dn" : "cn=Directory Manager",
   "bind_password" : "password",
   "connect_timeout_ms": 500,
   "response_timeout_ms": 200,
   "use_ssl" : true,
   "ssl_truststore_path": "config/ssl/trust.jks",
   "ssl_truststore_password": "secret"
  }
}

Host configuration examples

Basic with no fail-over

{
  "connection" : {
    "host" : "ldap-host",
    "port" : 389
  }
}

Enable failover by using hosts and adding more hosts

{
  "connection" : {
    "hosts" : "ldap-host:389,other-ldap:389"
  }
}

Custom TLS truststore

Set connection.ssl_truststore_path to a filesystem path string and connection.ssl_truststore_type to the file's type (JKS by default, or PKCS12). Keep ssl_trust_all: false. The client now reads the configured path as a string and honors the configured truststore type; a missing or invalid store, incorrect password, or untrusted server certificate must be corrected rather than bypassing validation.

Audit

Audit collection uses the platform's chain-based change model. The former module-level audit.create, audit.update, audit.delete, and AuditContext configuration no longer controls collection. Remove those legacy settings when migrating to the new platform.

Write valves publish change facts with the current execution's chain ID and operation identity. Deploy and configure the Audit module to collect and persist the trail. Optional valve-level audit hints describe object identity and change grouping; they are separate from the removed client-module switches. See Pipes audit guidance for those hints.

Events

Any write operation will generate an event.

Creating an object

• LDAP_001 - Object created

  • traceId, if present
  • object, the dn
  • attrNames, list of attribute names
  • attrCounts, attribute count

• LDAP_002 - Object creation failed

  • traceId, if present
  • object, the dn
  • resultCode from ldap if any

Deleting an object

• LDAP_003 - LDAP object deleted

  • traceId, if present
  • object, the dn

• LDAP_004 - LDAP object deletion failed

  • traceId, if present
  • object, the dn

Updating an object

• LDAP_007 - LDAP object updated
  • traceId, if present
  • object, the dn
  • attrNames, list of attribute names
  • attrCounts, attribute co
• LDAP_008 - LDAP update failed
  • traceId, if present
  • object, the dn

Moving an object

LDAP_005 - LDAP object moved

• traceId, if present
• object, the dn
• new_location

LDAP_006 - LDAP failed object move

• traceId, if present
• object, the dn