Extended standard RFCs operations
The extend.standard namespace contains extended operation defined in current RFCs:
extend.standard
extend.standard.who_am_i()
extend.standard.modify_password(
user,
old_password,
new_password,
hash_algorithm=None,
salt=None
)
extend.standard.paged_search(search_base,
search_filter,
search_scope,
dereference_aliases,
attributes,
size_limit,
time_limit,
types_only,
get_operational_attributes,
controls,
paged_size,
paged_criticality,
generator
)
extend.standard.persistent_search(
connection,
search_base,
search_filter,
search_scope,
dereference_aliases,
attributes,
size_limit,
time_limit,
controls,
changes_only,
events_type,
notifications,
streaming,
callback
)
To get the identity of the bound user:
c = Connection(....)
c.bind()
i_am = c.extend.standard.who_am_i()
if who_am_i() returns an empty string an anonymous connection is bound.
To modify a user password:
from ldap3 import Server, Connection, HASHED_SALTED_SHA256
s = Server(...)
c = Connection(s, ...)
c.bind() # bind as someone that has permission to change user's password
new_password = c.extend.standard.modify_password('cn=test1,o=test', 'old_password', 'new_password', HASHED_SALTED_SHA256) # a new password is set, hashed with sha256 and a random salt
A special case with modify_password is for LDAP servers that follow RFC3062. If you send the old password and do not specify a new password, the server should generate a new password compliant with the server password policy:
s = Server(...)
c = Connection(s, ...)
c.bind() # bind as someone that has permission to change user's password
new_password = c.extend.standard.modify_password('cn=test1,o=test', 'old_password') # a new password is generated by the server if compliant with RFC3062
The extend.standard.paged_search() operation is a convenient wrapper for the simple paged search as specified in the RFC2696. You can indicate how many entries will be read in the paged_size parameter (defaults to 100) and you get back a generator for the entries. If you set to False the generator parameter of the search will be fully executed before returning the results. If generator is set to True (the default) any subsequent search will be executed only when you read all the previous read entries, saving memory.
In the modify_password() extended operation you can specify an hashing algorithm, if your LDAP server use hashed password but don’t compute the hash by itself. Otherwise you can send the password and the server will hash it.
Algorithms names are defined in the ldap3 module. You can choose between:
HASHED_NONE (no hashing is performed, password is sent in plain text)
HASHED_MD5
HASHED_SHA
HASHED_SHA256
HASHED_SHA384
HASHED_SHA512
HASHED_SALTED_MD5
HASHED_SALTED_SHA
HASHED_SALTED_SHA256
HASHED_SALTED_SHA384
HASHED_SALTED_SHA512
If you don’t specify a salt parameter a random salt will be generated by the ldap3 library. Keep in mind that only salted password can provide a strong level of security against dictionary attacks.
To directly modify the userPassword attribute via a modify operation you probably have to send the hashed password. In this case you can use the hashed() function in the ldap3.utils.hashed package:
from ldap3 import HASHED_SALTED_SHA, MODIFY_REPLACE
from ldap3.utils.hashed import hashed
hashed_password = hashed(HASHED_SALTED_SHA, 'new_password')
c.modify('cn=user1,o=test', {'userPassword': [(MODIFY_REPLACE,[hashed_password])]})
To enable Persistent Searches to get all modification in the tree as they happens (for logging purpose):
from ldap3 import Server, Connection, ASYNC_STREAM
s = Server('myserver')
c = Connection(s, 'cn=admin,o=resources', 'password', client_strategy=ASYNC_STREAM)
c.stream = open('myfile.log', 'w+')
p = c.extend.standard.persistent_search()
now the persistent search is running in an internal thread. Each modification is recorded in the log in LDIF-CHANGE format, with the event type, event time and the modified dn and changelog number (if available) as comments.
This uses the AsyncStream Strategy, because the Persistent Search never sends the “SearchDone” packet, and this is not a valid LDAP3 behaviour. This is the reason for which the https://www.ietf.org/proceedings/50/I-D/ldapext-psearch-03.txt draft has never been approved as a standard RFC. The AsyncStream strategy sends each received packet to an external thread where it can be processed as soon as it is received.
In the persistent_search() method you can use the same parameter of a standard search. It also accepts some additional parameters specific of the persistent search:
def persistent_search(self,
search_base='',
search_filter='(objectclass=*)',
search_scope=SUBTREE,
dereference_aliases=DEREF_NEVER,
attributes=ALL_ATTRIBUTES,
size_limit=0,
time_limit=0,
controls=None,
changes_only=True,
show_additions=True,
show_deletions=True,
show_modifications=True,
show_dn_modifications=True,
notifications=True,
streaming=True,
callback=None
):
If you don’t pass any parameters the search should be globally applied in your LDAP server.
You can choose which kind of events to show with the show_* boolean parameters. notification=True allows you to receive the original dn of a modify_dn operation and the changelog number if provided by the server.
If you want to stop the persistent search you can use p.stop(). Use p.start() to start it again.
If you don’t provide a stream (a file to write to), a StringIO object is used. You can use it as a standard file or get the value of the StringIO object with c.stream.getvalue().
For example an output from my test suite is the following:
# 2016-07-10T23:34:41.616615
# add
dn: cn=[71973491]modify-dn-1,o=test
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: Person
objectClass: ndsLoginProperties
objectClass: Top
sn: modify-dn-1
cn: [71973491]modify-dn-1
ACL: 2#subtree#cn=[71973491]modify-dn-1,o=test#[All Attributes Rights]
ACL: 6#entry#cn=[71973491]modify-dn-1,o=test#loginScript
ACL: 2#entry#[Public]#messageServer
ACL: 2#entry#[Root]#groupMembership
ACL: 6#entry#cn=[71973491]modify-dn-1,o=test#printJobConfiguration
ACL: 2#entry#[Root]#networkAddress
# 2016-07-10T23:34:41.888506
# modify dn
# previous dn: cn=[71973491]modify-dn-1,o=test
dn: cn=[71973491]modified-dn-1,o=test
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: Person
objectClass: ndsLoginProperties
objectClass: Top
sn: modify-dn-1
cn: [71973491]modified-dn-1
ACL: 2#subtree#cn=[71973491]modified-dn-1,o=test#[All Attributes Rights]
ACL: 6#entry#cn=[71973491]modified-dn-1,o=test#loginScript
ACL: 2#entry#[Public]#messageServer
ACL: 2#entry#[Root]#groupMembership
ACL: 6#entry#cn=[71973491]modified-dn-1,o=test#printJobConfiguration
ACL: 2#entry#[Root]#networkAddress
# 2016-07-10T23:34:41.929022
# delete
dn: cn=[71973491]modified-dn-1,o=test
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: Person
objectClass: ndsLoginProperties
objectClass: Top
sn: modify-dn-1
cn: [71973491]modified-dn-1
ACL: 2#subtree#cn=[71973491]modified-dn-1,o=test#[All Attributes Rights]
ACL: 6#entry#cn=[71973491]modified-dn-1,o=test#loginScript
ACL: 2#entry#[Public]#messageServer
ACL: 2#entry#[Root]#groupMembership
ACL: 6#entry#cn=[71973491]modified-dn-1,o=test#printJobConfiguration
ACL: 2#entry#[Root]#networkAddress
If you call the persistent_search() method with streaming=False you can get the modified entries with the p.next() method. Each call to p.next(block=False, timeout=None) returns one event, with the extended control already decoded (as dict values) if available:
from ldap3 import Server, Connection, ASYNC_STREAM
s = Server('myserver')
c = Connection(s, 'cn=admin,o=resources', 'password', client_strategy=ASYNC_STREAM, auto_bind=True)
p = c.extend.standard.persistent_search(streaming=False)
p.start()
while True:
print(p.next(block=True))
When using next(block=False) or next(block=True, timeout=10) the method returns None if nothing is received from the server.
If you call the persistent_search() method with callback=myfunction (where myfunction is a callable, including lambda, accepting a dict as parameter) your function will be called for each event received in the persistent serach. The function will be called in the same thread of the persistent search, so it should not block.