MSLDAPClient – high level LDAP functions

class msldap.client.MSLDAPClient(target, creds)

High level API for LDAP operations.

target, creds, ldap_query_page_size

Parameters
  • target (MSLDAPTarget) – The target object describing the connection info

  • creds (MSLDAPCredential) – The credential object describing the authentication to be used

  • ldap_query_page_size (int) –

Returns

A dictionary representing the LDAP tree

Return type

dict

async add(dn, attributes)

Performs the add operation.

Parameters
  • dn (str) – The DN of the object to be added

  • attributes (dict) – Attributes to be used in the operation

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

async add_additional_hostname(user_dn, hostname)

Adds additional hostname to the user object.

Parameters

user_dn (str) – The user’s DN

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

async add_user_spn(user_dn, spn)

Adds an SPN record to the user object.

Parameters
  • user_dn (str) – The user’s DN

  • spn (str) – The SPN to be added. It must follow the SPN string format specifications.

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

async add_user_to_group(user_dn: str, group_dn: str)

Adds a user to a group

Parameters
  • user_dn (str) – The user’s DN

  • group_dn (str) – The groups’s DN

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

async change_password(user_dn: str, newpass: str, oldpass=None)

Changes the password of a user. If used with a high-privileged account (eg. Domain admin, Account operator…), the old password can be None

Parameters
  • user_dn (str) – The user’s DN

  • newpass (str) – The new password

  • oldpass (str) – The current password

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

async create_user_dn(user_dn, password)

Creates a new user object with a password and enables the user so it can be used immediately.

Parameters
  • user_dn (str) – The user’s DN

  • password (str) – The password of the user

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

async delete(dn)

Performs the delete operation.

Parameters

dn (str) – The DN of the object to be deleted

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

async delete_user(user_dn)

Deletes the user. This action is destructive!

Parameters

user_dn (str) – The user’s DN

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

async disable_user(user_dn)

Sets the user object to disabled by modifying the UserAccountControl attribute.

Parameters

user_dn (str) – The user’s DN

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

async enable_user(user_dn)

Sets the user object to enabled by modifying the UserAccountControl attribute.

Parameters

user_dn (str) – The user’s DN

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

async get_ad_info()

Polls for basic AD information (needed for determine password usage characteristics!)

Returns

A tuple with the domain information as MSADInfo and an Exception is there was any

Return type

(MSADInfo, Exception)

get_all_gpos()

Fetches all GPOs available in the LDAP tree and yields them as MSADGPO object.

Returns

Async generator which yields (MSADGPO, None) tuple on success or (None, Exception) on error

Return type

Iterator[(MSADGPO, Exception)]

get_all_groups()

Yields all Groups present in the LDAP tree.

Returns

Async generator which yields (MSADGroup, None) tuple on success or (None, Exception) on error

Return type

Iterator[(MSADGroup, Exception)]

get_all_knoreq_users(include_machine=False)

Fetches all user objects with useraccountcontrol DONT_REQ_PREAUTH flag set from the AD, and returns MSADUser object.

Parameters

include_machine (bool) – Specifies wether machine accounts should be included in the query

Returns

Async generator which yields (MSADUser, None) tuple on success or (None, Exception) on error

Return type

Iterator[(MSADUser, Exception)]

get_all_laps()

Fetches all LAPS passwords for all machines. This functionality is only available to specific high-privileged users.

Returns

Async generator which yields (dict, None) tuple on success or (None, Exception) on error

Return type

Iterator[(dict, Exception)]

get_all_machines(attrs=['accountExpires', 'badPasswordTime', 'badPwdCount', 'cn', 'description', 'codePage', 'countryCode', 'displayName', 'distinguishedName', 'dNSHostName', 'instanceType', 'isCriticalSystemObject', 'lastLogoff', 'lastLogon', 'lastLogonTimestamp', 'logonCount', 'localPolicyFlags', 'msDS-SupportedEncryptionTypes', 'name', 'objectCategory', 'objectClass', 'objectGUID', 'objectSid', 'operatingSystem', 'operatingSystemVersion', 'primaryGroupID', 'pwdLastSet', 'sAMAccountName', 'sAMAccountType', 'sn', 'userAccountControl', 'whenChanged', 'whenCreated', 'servicePrincipalName', 'msDS-AllowedToDelegateTo', 'msDS-AllowedToActOnBehalfOfOtherIdentity'])

Fetches all machine objects available in the LDAP tree and yields them as MSADMachine object.

Parameters

attrs (list) – Lists of attributes to request (eg. [‘sAMAccountName’, ‘dNSHostName’]) Default: all attrs.

Returns

Async generator which yields (MSADMachine, None) tuple on success or (None, Exception) on error

Return type

Iterator[(MSADMachine, Exception)]

get_all_objectacl()

Yields the security descriptor of all objects in the LDAP tree of the following types: Users, Computers, GPOs, OUs, Groups

Returns

Async generator which yields (MSADSecurityInfo, None) tuple on success or (None, Exception) on error

Return type

Iterator[(MSADSecurityInfo, Exception)]

get_all_ous()

Yields all OUs present in the LDAP tree.

Returns

Async generator which yields (MSADOU, None) tuple on success or (None, Exception) on error

Return type

Iterator[(MSADOU, Exception)]

get_all_service_users(include_machine=False)

Fetches all service user objects from the AD, and returns MSADUser object. Service user refers to an user with SPN (servicePrincipalName) attribute set

Parameters

include_machine (bool) – Specifies wether machine accounts should be included in the query

Returns

Async generator which yields (MSADUser, None) tuple on success or (None, Exception) on error

Return type

Iterator[(MSADUser, Exception)]

get_all_spn_entries()

Fetches all service user objects from the AD, and returns MSADUser object. Service user refers to an user with SPN (servicePrincipalName) attribute set

Parameters

include_machine (bool) – Specifies wether machine accounts should be included in the query

Returns

Async generator which yields tuples with a string in SPN format and an Exception if there was any

Return type

Iterator[(str, Exception)]

get_all_tokengroups()

Yields all effective group membership information for all objects of the following type: Users, Groups, Computers

Returns

Async generator which yields (dict, None) tuple on success or (None, Exception) on error

Return type

Iterator[(dict, Exception)]

get_all_trusts()

Yields all trusted domains.

Returns

Async generator which yields (MSADDomainTrust, None) tuple on success or (None, Exception) on error

Return type

Iterator[(MSADDomainTrust, Exception)]

get_all_users()

Fetches all user objects available in the LDAP tree and yields them as MSADUser object.

Returns

Async generator which yields (MSADUser, None) tuple on success or (None, Exception) on error

Return type

Iterator[(MSADUser, Exception)]

async get_dn_for_objectsid(objectsid)

Fetches the DN for an object specified by objectsid

Parameters

objectsid (str) – The object’s SID

Returns

The distinguishedName

Return type

(str, Exception)

async get_group_by_dn(group_dn)

Returns an MSADGroup object for the group specified by group_dn

Parameters

group_dn (str) – The user’s DN

Returns

tuple of MSADGroup and an Exception is there was any

Return type

(MSADGroup, Exception)

get_group_members(dn, recursive=False)

Fetches the DN for an object specified by objectsid

Parameters
  • dn (str) – The object’s DN

  • recursive (bool) – Indicates wether the lookup should recursively affect all groups

Returns

Async generator which yields (MSADUser, None) tuple on success or (None, Exception) on error

Return type

Iterator[(MSADUser, Exception)]

async get_laps(sAMAccountName)

Fetches the LAPS password for a machine. This functionality is only available to specific high-privileged users.

Parameters

sAMAccountName (str) – The username of the machine (eg. COMP123$).

Returns

Laps attributes as a dict

Return type

(dict, Exception)

async get_objectacl_by_dn(dn, flags=<SDFlagsRequest.DACL_SECURITY_INFORMATION|GROUP_SECURITY_INFORMATION|OWNER_SECURITY_INFORMATION: 7>)

Returns the full or partial Security Descriptor of the object specified by it’s DN. The flags indicate which part of the security Descriptor to be returned. By default the full SD info is returned.

Parameters
  • object_dn (str) – The object’s DN

  • flags (SDFlagsRequest) – Flags indicate the data type to be returned.

Returns

nTSecurityDescriptor attribute of the object as bytes and an Exception is there was any

Return type

(bytes, Exception)

get_tokengroups(dn)

Yields SIDs of groups that the given DN is a member of.

Returns

Async generator which yields (str, None) tuple on success or (None, Exception) on error

Return type

Iterator[(str, Exception)]

async get_tree_plot(root_dn, level=2)

Returns a dictionary representing a tree starting from ‘dn’ containing all subtrees.

Parameters
  • root_dn (str) – The start DN of the tree

  • level (int) – Recursion level

Returns

A dictionary representing the LDAP tree

Return type

dict

async get_user(sAMAccountName)

Fetches one user object from the AD, based on the sAMAccountName attribute (read: username)

Parameters

sAMAccountName (str) – The username of the user.

Returns

A tuple with the user as MSADUser and an Exception is there was any

Return type

(MSADUser, Exception)

async get_user_by_dn(user_dn)

Fetches the DN for an object specified by user_dn

Parameters

user_dn (str) – The user’s DN

Returns

The user object

Return type

(MSADUser, Exception)

async modify(dn, changes, controls=None)

Performs the modify operation.

Parameters
  • dn (str) – The DN of the object whose attributes are to be modified

  • changes (dict) – Describes the changes to be made on the object. Must be a dictionary of the following format: {‘attribute’: [(‘change_type’, [value])]}

  • controls (dict) – additional controls to be passed in the query

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)

pagedsearch(query, attributes, controls=None)
Performs a paged search on the AD, using the filter and attributes as a normal query does.

!The LDAP connection MUST be active before invoking this function!

Parameters
  • query (str) – LDAP query filter

  • attributes (List[str]) – List of requested attributes

  • controls (dict) – additional controls to be passed in the query

  • level (int) – Recursion level

Returns

Async generator which yields (dict, None) tuple on success or (None, Exception) on error

Return type

Iterator[(dict, Exception)]

async set_objectacl_by_dn(object_dn, data, flags=<SDFlagsRequest.DACL_SECURITY_INFORMATION|GROUP_SECURITY_INFORMATION|OWNER_SECURITY_INFORMATION: 7>)

Updates the security descriptor of the LDAP object

Parameters
  • object_dn (str) – The object’s DN

  • data (bytes) – The actual data as bytearray to be updated in the Security Descriptor of the specified object

  • flags (SDFlagsRequest) – Flags indicate the data type to be updated.

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

tuple

async unlock_user(user_dn)

Unlocks the user by clearing the lockoutTime attribute.

Parameters

user_dn (str) – The user’s DN

Returns

A tuple of (True, None) on success or (False, Exception) on error.

Return type

(bool, Exception)