MSLDAPClient – high level LDAP functions¶

class msldap.client.MSLDAPClient(target: MSLDAPTarget, creds: UniCredential, connection=None, keepalive=False)¶

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: str, attributes: Dict[str, object])¶

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: str, hostname: str)¶

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: str, spn: str)¶

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: Optional[str] = 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: str, password: str)¶

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: str)¶

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: str)¶

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: str)¶

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: str)¶

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)

async get_all_gpos(attrs: List[str] = ['cn', 'displayName', 'distinguishedName', 'flags', 'gPCFileSysPath', 'gPCFunctionalityVersion', 'gPCMachineExtensionNames', 'gPCUserExtensionNames', 'objectClass', 'objectGUID', 'systemFlags', 'versionNumber', 'whenChanged', 'whenCreated'])¶

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)]

async get_all_groups(attrs: List[str] = ['cn', 'distinguishedName', 'objectGUID', 'objectSid', 'groupType', 'instanceType', 'name', 'member', 'sAMAccountName', 'systemFlags', 'whenChanged', 'whenCreated', 'description', 'nTSecurityDescriptor', 'sAMAccountType'])¶

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)]

async get_all_knoreq_users(include_machine: bool = 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)]

async 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)]

async get_all_machines(attrs: List[str] = ['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)]

async 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)]

async 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)]

async get_all_service_users(include_machine: bool = 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)]

async 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)]

async 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)]

async 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)]

async get_all_users(attrs: List[str] = ['accountExpires', 'badPasswordTime', 'badPwdCount', 'cn', 'codePage', 'countryCode', 'displayName', 'distinguishedName', 'givenName', 'initials', 'lastLogoff', 'lastLogon', 'lastLogonTimestamp', 'logonCount', 'name', 'description', 'objectCategory', 'objectClass', 'objectGUID', 'objectSid', 'primaryGroupID', 'pwdLastSet', 'sAMAccountName', 'sAMAccountType', 'sn', 'userAccountControl', 'userPrincipalName', 'whenChanged', 'whenCreated', 'memberOf', 'member', 'servicePrincipalName', 'msDS-AllowedToDelegateTo', 'adminCount'])¶

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: str)¶

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: str)¶

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)

async get_group_members(dn: str, recursive: bool = 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: str)¶

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: str, flags: ~msldap.wintypes.asn1.sdflagsrequest.SDFlagsRequest = SDFlagsRequest.None)¶

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)

async get_tokengroups(dn: str)¶

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: str, level: int = 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: str)¶

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: str)¶

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: str, changes: Dict[str, object], controls: Optional[Dict[str, object]] = 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)

async pagedsearch(query: str, attributes: List[str], controls: Optional[List[Tuple[str, str, str]]] = None, tree: Optional[str] = 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
tree (str) – Base tree to perform the search on

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: str, data: bytes, flags: ~msldap.wintypes.asn1.sdflagsrequest.SDFlagsRequest = SDFlagsRequest.None)¶

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: str)¶

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)

MSLDAPClient – high level LDAP functions¶

msldap

Navigation

Related Topics