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"
  }
}

Audit

The LdapClient can record an audit trail for write operations (add, modify, delete). Audit logging is disabled by default and must be explicitly enabled per operation type.

When audit is enabled, the caller is expected to supply an AuditContext containing the subject (the authenticated user performing the operation) and a correlation ID. The LDAP valves automatically construct this context from the session and the pipe trace ID.

Note

Audit events are published fire-and-forget on the internal event bus. If no audit module is running, events are silently dropped — no errors are returned to the caller.

Configuration

The audit block is placed at the top level of the module config, alongside connection.

Properties

Name	Description	Default	Mandatory
audit.create	Record an audit event when an LDAP entry is added.	false
audit.update	Record an audit event when an LDAP entry is modified.	false
audit.delete	Record an audit event when an LDAP entry is deleted.	false

Example

{
  "name": "LdapClient",
  "config": {
    "name": "default",
    "connection": {
      "host": "127.0.0.1",
      "port": 389,
      "bind_dn": "cn=Directory Manager",
      "bind_password": "password"
    },
    "audit": {
      "create": true,
      "update": true,
      "delete": true
    }
  }
}

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