> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/ldapclient/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/ldapclient/readme.md).

# LdapClient

## Introduction

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

Each module (instance) manages a single connection to a single directory (a destination) with the possibility to add more identical directories for fail over. To configure connections to multiple servers, use multiple modules. To increase throughput, increase the number of module instances.

The module provides a service on the internal event bus 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

{% hint style="info" %}
**Module name:** `LdapClient | LDAPClient`
{% endhint %}

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th>Name</th><th>Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>name</code></td><td>Destination name. Unique identifier for a specific configuration/connection/service. This value must be unique for all ldapclient configurations.</td><td><code>"default"</code></td><td>false</td></tr><tr><td><code>instances</code></td><td>Number of instances to deploy.</td><td><code>1</code></td><td>false</td></tr><tr><td><code>connection</code></td><td>LDAP <a href="#connection">connection</a> configuration</td><td></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
  "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
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Connection

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="241">Name</th><th width="230">Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>host</code></td><td>Hostname or Ip-address to LDAP directory service. (Mandatory unless <code>hosts</code> is used)</td><td></td><td>true</td></tr><tr><td><code>port</code></td><td>Listen port of LDAP directory service. (Mandatory unless <code>hosts</code> is used)</td><td></td><td>true</td></tr><tr><td><code>hosts</code></td><td>List of LDAP directory service hosts:ports. If more than one is specified, fail-over is enabled. When this property is used, <code>host</code> and <code>port</code> properties are optional.</td><td></td><td>false</td></tr><tr><td><code>bind_dn</code></td><td>DN of user/account used to connect to LDAP service.</td><td></td><td>false</td></tr><tr><td><code>bind_password</code></td><td>Password of user/account used to connect to LDAP service.</td><td></td><td>false</td></tr><tr><td><code>connect_timeout_ms</code></td><td>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.</td><td><code>10000</code></td><td>false</td></tr><tr><td><code>response_timeout_ms</code></td><td>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.</td><td><code>2000</code></td><td>false</td></tr><tr><td><code>abandon_on_timeout</code></td><td>Specifies whether the LDAP client should attempt to abandon any request for which no response is received in the maximum response timeout period.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>follow_referrals</code></td><td>Specifies whether associated connections should attempt to follow any referrals that they encounter, using the referral connector for the associated connection.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>use_keep_alive</code></td><td>Specifies whether to use the <code>SO_KEEPALIVE</code> option for the underlying sockets used by associated connections.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>use_linger</code></td><td>Specifies whether to use the <code>SO_LINGER</code> option for the underlying sockets used by associated connections.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>linger_timeout_secs</code></td><td><code>SO_LINGER</code> timeout in seconds.</td><td><code>30</code></td><td>false</td></tr><tr><td><code>use_schema</code></td><td>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).</td><td><code>false</code></td><td>false</td></tr><tr><td><code>use_ssl</code></td><td>Specifies if SSL/TLS should be used or not.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>ssl_trust_all</code></td><td>Turns on/off trust validation for SSL/TLS connections.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>ssl_truststore_path</code></td><td>Path to custom SSL truststore. If not specified, the default Java truststore will be used.</td><td></td><td>false</td></tr><tr><td><code>ssl_truststore_password</code></td><td>Custom truststore password</td><td></td><td>false</td></tr><tr><td><code>ssl_truststore_validate_time</code></td><td>Turns on/off peer certificate validity check.</td><td><code>true</code></td><td>false</td></tr><tr><td><code>is_active_directory</code></td><td>Turns on/off Active Directory specific paginated search results.</td><td><code>true</code></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

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

{% endtab %}
{% endtabs %}

#### Host configuration examples

Basic with no fail-over

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

Enable failover by using `hosts` and adding more hosts

```json
"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.

{% hint style="info" %}
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.
{% endhint %}

### Configuration

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

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="180">Name</th><th width="320">Description</th><th>Default</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>audit.create</code></td><td>Record an audit event when an LDAP entry is added.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>audit.update</code></td><td>Record an audit event when an LDAP entry is modified.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>audit.delete</code></td><td>Record an audit event when an LDAP entry is deleted.</td><td><code>false</code></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
  "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
    }
  }
}
```

{% endtab %}
{% endtabs %}

## 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fortifiedid.se/ldapclient/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.