0
# LDAP3
1

2
A strictly RFC 4510 conforming LDAP V3 pure Python client library that works across Python 2, Python 3, PyPy, PyPy3, and Nuikta. LDAP3 provides comprehensive LDAP directory services interaction capabilities with support for synchronous and asynchronous operations, various authentication methods, server pooling, and an abstraction layer for simplified programming.
3

4
## Package Information
5

6
- **Package Name**: ldap3
7
- **Language**: Python
8
- **Installation**: `pip install ldap3`
9
- **Version**: 1.4.0
10
- **License**: LGPL v3
11

12
## Core Imports
13

14
```python
15
import ldap3
16
```
17

18
Common import patterns:
19

20
```python
21
from ldap3 import Server, Connection, ALL, SUBTREE
22
```
23

24
Import authentication and strategy constants:
25

26
```python
27
from ldap3 import SIMPLE, SASL, SYNC, ASYNC, AUTO_BIND_NO_TLS
28
```
29

30
Import additional classes and utilities:
31

32
```python
33
from ldap3 import Tls, ServerPool, DsaInfo, SchemaInfo
34
from ldap3 import ObjectDef, AttrDef, Entry, Reader, Attribute, OperationalAttribute
35
```
36

37
Import exceptions for error handling:
38

39
```python
40
from ldap3 import (LDAPException, LDAPBindError, LDAPInvalidCredentialsResult,
41
                   LDAPInsufficientAccessRightsResult, LDAPCommunicationError)
42
```
43

44
## Basic Usage
45

46
```python
47
import ldap3
48

49
# Create server and connection
50
server = ldap3.Server('ldap://ldap.example.com', get_info=ldap3.ALL)
51
conn = ldap3.Connection(server, 'cn=admin,dc=example,dc=com', 'password', auto_bind=True)
52

53
# Perform a search
54
conn.search('dc=example,dc=com', '(objectClass=person)', attributes=['cn', 'mail'])
55

56
# Access results
57
for entry in conn.entries:
58
    print(f"Name: {entry.cn}, Email: {entry.mail}")
59

60
# Add an entry
61
conn.add('cn=newuser,dc=example,dc=com', 
62
         object_class=['inetOrgPerson'], 
63
         attributes={'cn': 'New User', 'sn': 'User', 'mail': 'newuser@example.com'})
64

65
# Modify an entry
66
conn.modify('cn=newuser,dc=example,dc=com', {'mail': [(ldap3.MODIFY_REPLACE, 'updated@example.com')]})
67

68
# Delete an entry
69
conn.delete('cn=newuser,dc=example,dc=com')
70

71
# Close connection
72
conn.unbind()
73
```
74

75
## Architecture
76

77
LDAP3 provides a layered architecture:
78

79
- **Connection Layer**: Server definitions, connection management, pooling, and TLS/SSL support
80
- **Operation Layer**: Core LDAP operations (bind, search, add, modify, delete) with multiple client strategies
81
- **Protocol Layer**: RFC-compliant LDAP protocol implementation with extensible controls and operations
82
- **Abstract Layer**: High-level ORM-like interface for easier entry and attribute manipulation
83
- **Extension Layer**: Extended operations for specific LDAP server implementations (Microsoft AD, Novell eDirectory)
84

85
This design enables both low-level protocol control and high-level abstraction, making it suitable for everything from simple directory queries to complex enterprise LDAP applications.
86

87
## Capabilities
88

89
### Core Connection and Server Management
90

91
Server definition, connection establishment, authentication methods, TLS/SSL configuration, server pooling for high availability, and connection strategies for different use cases.
92

93
```python { .api }
94
class Server:
95
    def __init__(self, host, port=None, use_ssl=False, allowed_referral_hosts=None, 
96
                 get_info=NONE, tls=None, formatter=None, connect_timeout=None, 
97
                 mode=IP_V6_PREFERRED): ...
98

99
class Connection:
100
    def __init__(self, server, user=None, password=None, auto_bind=AUTO_BIND_NONE,
101
                 version=3, authentication=None, client_strategy=SYNC, 
102
                 auto_referrals=True, auto_range=False, sasl_mechanism=None,
103
                 sasl_credentials=None, check_names=True, collect_usage=False,
104
                 read_only=False, lazy=False, raise_exceptions=False, 
105
                 pool_name=None, pool_size=None, pool_lifetime=None, 
106
                 fast_decoder=True, receive_timeout=None, 
107
                 return_empty_attributes=False): ...
108
    
109
    def bind(self, user=None, password=None, sasl_mechanism=None, sasl_credentials=None): ...
110
    def unbind(self, controls=None): ...
111
    def rebind(self, user=None, password=None, authentication=None, sasl_mechanism=None, sasl_credentials=None): ...
112
    def extended(self, request_name, request_value=None, controls=None, no_encode=None): ...
113
    
114
    @property
115
    def entries(self): ...
116
    @property 
117
    def stream(self): ...
118

119
class ServerPool:
120
    def __init__(self, servers=None, pool_strategy=ROUND_ROBIN, active=True, exhaust=False): ...
121
```
122

123
[Core Connection and Server Management](./connection.md)
124

125
### LDAP Operations
126

127
All standard LDAP operations including search, add, modify, delete, compare, and abandon operations with full control support and multiple response formats.
128

129
```python { .api }
130
# Core LDAP operations on Connection class
131
def search(self, search_base, search_filter, search_scope=SUBTREE, 
132
           dereference_aliases=DEREF_ALWAYS, attributes=None, size_limit=0, 
133
           time_limit=0, types_only=False, get_operational_attributes=False, 
134
           controls=None, paged_size=None, paged_criticality=False, 
135
           paged_cookie=None): ...
136

137
def add(self, dn, object_class=None, attributes=None, controls=None): ...
138
def delete(self, dn, controls=None): ...
139
def modify(self, dn, changes, controls=None): ...
140
def modify_dn(self, dn, relative_dn, delete_old_dn=True, new_superior=None, controls=None): ...
141
def compare(self, dn, attribute, value, controls=None): ...
142
```
143

144
[LDAP Operations](./operations.md)
145

146
### Abstract Layer
147

148
High-level ORM-like interface with object definitions, attribute definitions, entry objects, and reader classes for simplified LDAP programming.
149

150
```python { .api }
151
class ObjectDef:
152
    def __init__(self, object_class=None): ...
153

154
class AttrDef:
155
    def __init__(self, name, key=None, validate=None, pre_query=None, post_query=None,
156
                 default=NotImplemented, dereference_dn=None, description=None): ...
157

158
class Entry:
159
    def __init__(self, dn, reader): ...
160
    def entry_get_dn(self): ...
161
    def entry_to_json(self): ...
162
    def entry_to_ldif(self): ...
163

164
class Reader:
165
    def __init__(self, connection, object_def, query, base, components_in_and=True,
166
                 sub_tree=True, get_operational_attributes=False, controls=None): ...
167
    def search(self): ...
168
```
169

170
[Abstract Layer](./abstract.md)
171

172
### Extended Operations
173

174
Extended operations for specific LDAP server implementations including Microsoft Active Directory, Novell eDirectory, and standard RFC extensions.
175

176
```python { .api }
177
# Standard extended operations (connection.extend.standard)
178
def who_am_i(self, controls=None): ...
179
def modify_password(self, user, old_password, new_password, hash_algorithm=None, 
180
                   salt=None, controls=None): ...
181

182
# Microsoft AD extended operations (connection.extend.microsoft)  
183
def dir_sync(self, sync_base, sync_filter, sync_attributes=None, cookie=None, 
184
             object_security=False, ancestors_first=False, public_data_only=False,
185
             incremental_values=False, max_length=2147483647, hex_guid=False, controls=None): ...
186

187
# Novell eDirectory extended operations (connection.extend.novell)
188
def get_bind_dn(self, controls=None): ...
189
def start_transaction(self, controls=None): ...
190
def end_transaction(self, commit=True, controls=None): ...
191
```
192

193
[Extended Operations](./extended.md)
194

195
### Configuration and Utilities
196

197
Configuration parameters, constants, exception handling, utility functions, and protocol information classes.
198

199
```python { .api }
200
def get_config_parameter(parameter): ...
201
def set_config_parameter(parameter, value): ...
202

203
class DsaInfo:
204
    def __init__(self, attributes, raw_attributes): ...
205
    @staticmethod
206
    def from_json(json_info): ...
207

208
class SchemaInfo:
209
    def __init__(self, schema_dn, attributes, raw_attributes): ...
210
    @staticmethod  
211
    def from_json(json_schema): ...
212
```
213

214
[Configuration and Utilities](./config.md)
215

216
## Constants
217

218
### Authentication Methods
219
- `ANONYMOUS` - Anonymous authentication
220
- `SIMPLE` - Simple bind authentication
221
- `SASL` - SASL authentication  
222
- `NTLM` - NTLM authentication
223

224
### Client Strategies
225
- `SYNC` - Synchronous strategy
226
- `ASYNC` - Asynchronous strategy
227
- `LDIF` - LDIF producer strategy
228
- `RESTARTABLE` - Restartable strategy
229
- `REUSABLE` - Reusable threaded strategy
230

231
### Search Scopes  
232
- `BASE` - Base object scope
233
- `LEVEL` - Single level scope
234
- `SUBTREE` - Whole subtree scope
235

236
### Modify Operations
237
- `MODIFY_ADD` - Add attribute values
238
- `MODIFY_DELETE` - Delete attribute values
239
- `MODIFY_REPLACE` - Replace attribute values
240
- `MODIFY_INCREMENT` - Increment attribute values
241

242
### Auto-bind Options
243
- `AUTO_BIND_NONE` - No auto-binding
244
- `AUTO_BIND_NO_TLS` - Auto-bind without TLS
245
- `AUTO_BIND_TLS_BEFORE_BIND` - Start TLS before binding
246
- `AUTO_BIND_TLS_AFTER_BIND` - Start TLS after binding
247

248
## Exception Hierarchy
249

250
```python { .api }
251
class LDAPException(Exception): ...
252

253
# Configuration exceptions
254
class LDAPConfigurationError(LDAPException): ...
255
class LDAPDefinitionError(LDAPException): ...
256

257
# Connection exceptions  
258
class LDAPBindError(LDAPException): ...
259
class LDAPInvalidServerError(LDAPException): ...
260
class LDAPCommunicationError(LDAPException): ...
261

262
# Operation result exceptions
263
class LDAPOperationResult(LDAPException): ...
264
class LDAPInvalidCredentialsResult(LDAPOperationResult): ...
265
class LDAPInsufficientAccessRightsResult(LDAPOperationResult): ...
266
```