read-ad 0.7.0

COM-based readonly access for Active Directory in Python 3

python-read-ad

COM-based readonly access for Active Directory in Python, forked from Tim Golden's active_directory.py v0.6.7

Module description

Module name: read_ad

Dependencies: Python 3.x and the pywin32 module (https://pypi.org/project/pywin32/)

Goals: minimum dependencies, maximum speed, easy usage.

In contrast to the original, this module provides read access only. For full-featured Active Directory access, please refer to the latest version of the original, hosted at https://github.com/tjguk/active_directory.

Module contents

Constants / Global Variables

Handling Active Directory times

BASE_TIME

A datetime.datetime instance with a value of 1601-01-01T00:00:00, the base date of all Active Directory times.

TIME_NEVER_HIGH_PART

0x7fffffff - the high 32 bit part of the Active Directory timestanp reserved for "never".

TIME_NEVER_KEYWORD

'<never>' - a textual replacement for an Active Directory "never" time.

Constants for ADO/COM access

ADO_COMMAND

'ADODB.Command'

ADO_CONNECTION

'ADODB.Connection'

CONNECTION_PROVIDER

'ADsDSOObject'

CONNECTION_TARGET

'Active Directory Provider'

Internal cache keywords

CACHE_KEY_CONNECTION

'_Connection_' as the key for caching the connection object.

CACHE_KEY_ROOT

'_ActiveDirectoryRoot_' as the key for caching the Active Directory root URL.

Mappings

GLOBAL_CACHE

A global cache of LdapEntry objects mapped to LDAP Urls, plus the connection object and the Active Directory root URL.

GROUP_TYPES

A FlagsMapping() with Active Directory group type bitmasks (values are taken from https://github.com/tjguk/active_directory/blob/master/active_directory.py#L164)

AUTHENTICATION_TYPES

A FlagsMapping() with Active Directory authentication type bitmasks (values are taken from https://github.com/tjguk/active_directory/blob/master/active_directory.py#L172)

SAM_ACCOUNT_TYPES

A UnsignedIntegerMapping() with Active Directory account type magic numbers (values are taken from https://github.com/tjguk/active_directory/blob/master/active_directory.py#L187)

USER_ACCOUNT_CONTROL

A FlagsMapping() with Active Directory user account state bitmasks (values are taken from https://github.com/tjguk/active_directory/blob/master/active_directory.py#L202)

SEARCH_FILTERS

A dict of SearchFilter instances mapped to the following keywords:

• 'computer' for searching computers by cn
• 'group' for searching groups by cn
• 'ou' for searching organizational units by ou
• 'public_folder' for searching public folders by displayName
• 'userid' for searching users by sAMAccountName

Classes

UnsignedIntegerMapping(**kwargs)

A Mapping of unsigned integers to names with reverse lookup functionality. Member access usng a name returns the associated number und vice versa.

.get_name(number)

Explicitly returns the name associated with the given number.

FlagsMapping(**kwargs)

An UnsignedIntegerMapping subclass for bitmasks mapped to flag names

.get_flag_names(number)

Returns a set of all flag names for the bitmasks matching the given number.

Recordset(record)

Wrapper around an ADO recordset as documented at https://docs.microsoft.com/windows/win32/adsi/searching-with-activex-data-objects-ado

.query(query_string, **kwargs)

Classmethod that executes an Active Directory query over a cached connection (provided by the connection() helper function, see source code) and returns an iterator over RecordSet instances for each found result.

The query may be parameterized using keyword arguments. Underscores in the keywords will be replaced by spaces.

The following parametrs are preset for the query but may be overridden:

• Asynchronous=True
• Timeout=1

.dump_fields()

Returns an iterator over the recordset fields as (fname, value) tuples

PathComponent(keyword, value)

Instances of this class represent a single component of an LDAP path, eg 'cn=Users'. They are initialized with a keyword and a value, in this example: 'cn' and 'Users'.

.keyword

The keyword

.value

The value

.from_string(string)

Constructor (class)method, returns a PathComponent instance built from keyword and value determined by splitting string at a non-escaped equals sign (=).

LdapPath(*parts)

Instances of this class represent an LDAP path. They are initialized using the provided parts, which can be strings or PathComponent instances.

.components

The components of the path (a tuple of PathComponent instances)

.rdn

The relative distinguished name of the LPAP path (the .value of the first component)

.url

The LDAP URL of the path (the distinguished name prefixed with 'LDAP://')

.from_string(string)

Constructor (class)method, returns an LdapPath instance built from the provided string splitted at all non-escaped commas (,).

SearchFilter(primary_key_name, **fixed_parameters)

Instances of this class hold a primary key name and a mapping of fixed parameters for an LDAP search.

.execute_query(ldap_path, *args, **kwargs)

Return an interator from the result of an LDAP query (using the RecordSet.query() class method) starting at the URL of the provided LdapPath instance, using SQL syntax with the WHERE clause genarated by .where_clause() method.

.where_clause(*args, **kwargs)

Return a WHERE clause for an SQL-like LDAP query string, built from the provided positional and keyword arguments, all concatenated unsing AND.
The stored fixed parameters override the provided keyword arguments. If a _primary_key_ keyword was provided, its value is built into the clause using the stored primary key name.

LdapEntry(com_object)

Stores a subset of an LDAP entry's properties. The stored properties can be accessed via item access using [property_name] or (in the case of suitable property names) via attribute access using .property_name

This is the base class for objects from the Active Directory.

All LdapPath subclasses instances should be instantiated by using the produce_entry() function below.

.empty_properties

A sorted list of the names of all properties having the value None.

.parent

An LdapEntry subclass instance of the current entry's parent

.path

An LdapPath instance from the ADsPath property

.child(single_path_component)

Returns an LdapEntry subclass instance for a relative child of this instance. Its path is determined by prepending the single_path_component to this instance's path.

.items()

Returns an iterator over the property names and their values as dict items (if the value is not None).

.print_dump()

Prints a case-sensitive (i.e. uppercase before lowercase) alphabetically sorted dump of non-empty properties.

User(com_object)

LdapEntry subclass for Active Directory users

Interesting properties include:

• sAMAccountName - the user ID
• givenName - the first name
• sn - the last name
• title - eg a PhD
• manager - the user's direct boss (distinguished name)
• memberOf - all groups the user is a direct member of (a tuple of distinguished names)
• userAccountControl - originally a number, but resolved to a set of flag names from USER_ACCOUNT_CONTROL

.account_disabled

True if the account is disabled, False if it is active.

Group(com_object)

LdapEntry subclass for Active Directory groups

Interesting properties include:

• member - all direct members (users and groups, a tuple of distinguished names)
• memberOf - all groups this group is a direct member of (a tuple of distinguished names)

.walk()

Returns an iterator over tuples, each consisting of: 1. the current Group instance, 2. a list of member Group instances and 3. a list of member User instances.

Computer(com_object)

LdapEntry subclass for Active Directory computers

OrganizationalUnit(com_object)

LdapEntry subclass for Active Directory organizational units, supporting searches

.find(*args, **kwargs)

Returns an LdapEntry subclass instance made from the first found LDAP entry from an LDAP search using .search(), or None if nothing was found.

If the positional arguments (*args) do not contain valid conditions for the query's WHERE clause, the RecordSet.query() method execting the query will return a ValueError and display the faulty query string.

.find_user(*args, **kwargs)

Returns a User instance made from the first found LDAP entry from an LDAP search using .search(), or None if nothing was found.

In contrary to the .find() method above, the first positional argument - if any are provided - is treated differently:
It is matched against each one of sAMAccountName, displayName and cn by building suitable conditions joined by 'OR' into the query's WHERE clause. Remaining positional arguments are treated as in .find().

The search_filter argument for .search() is set to the user search filter (SEARCH_FILTER['userid']).

.search(*args, active=None, search_filter=None, **kwargs)

Returns an iterator over all found LDAP paths from an LDAP search starting at this instance's path.

If active is set to True or False explicitly, the method returns only the paths of active (or deactivated) matching entries.

If search_filter is set to a SearchFilter instance, this method uses that instance to search the Active Directory. Else, if a keyword matching any of the SEARCH_FILTERS keys was provided, that search filter is used with this keyword's value specified as the _primary_key_ keyword's value.
In all other cases, an empty search filter will be instantiated and used.

DomainDNS(com_object)

OrganizationalUnit subclass for the Active Directory domain DNS

PublicFolder(com_object)

LdapEntry subclass for Active Directory public folders

Public interface functions

produce_entry(ldap_path, lazy=True)

LdapEntry subclass factory function.

Determines the suitable LdapEntry subclass from the COM object found at the LDAP URL. Generates an instance of this class from the COM object, stores it in GLOBAL_CACHE (associated to the LDAP path URL), and returns the Instance.

ldap_path may be a string containing either a distinguished name or an LDAP URL (which is basically a distinguished name prefixed with 'LDAP://'), or an LdapPath instance.

if lazy is set to True (the default), this function returns the suitable cached entry if it exists, avoiding expensive lookups and network traffic.

root(server=None)

Returns the (cached) DomainDNS instance referring to the root of the logged-on Active Directory tree.

find(*args, **kwargs)

Returns an LdapEntry subclass instance made from the first found LDAP entry from an LDAP search starting at the active Directory root's path, or None if nothing was found.

See the documentation of the OrganizationalUnit's method for the treatment of arguments and keyword arguments.

find_user(*args, **kwargs)

Returns a User instance made from the first found LDAP entry from an LDAP search starting at the active Directory root's path, or None if nothing was found.

See the documentation of the OrganizationalUnit's method for the treatment of arguments and keyword arguments.

search(*args, **kwargs)

Returns an iterator over all found LDAP paths from an LDAP search starting at the active Directory root's path.

See the documentation of the OrganizationalUnit's method for the treatment of arguments and keyword arguments.

Examples

import read_ad

# read_ad.root() returns the cached Active Directory root entry

# find your own user in active directory
import getpass
my_user = read_ad.find_user(getpass.getuser())