read-ad 0.8.1

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

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_url, *args, **kwargs)

Return an interator from the result of an LDAP query (using the RecordSet.query() class method) starting at ldap_url and using SQL syntax with the WHERE clause genarated by the .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 using 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 and 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.

.ldap_url

The LDAP URL of the entry.

.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.

Public interface functions

produce_entry(ldap_path, lazy=True)

LdapEntry and subclasses factory function.

Determines the suitable class out of LdapEntry, User or Group 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.

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

Returns an iterator over all found LDAP paths from an LDAP search starting at the LDAP URL specified as search_base. If search_base is not given, the LDAP search starts at the LDAP URL of root().

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.

If positional arguments (*args) were provided and any of them does not contain a valid condition for the query's WHERE clause, the RecordSet.query() method execting the query will return a ValueError and display the faulty query string.

search_users(*args, **kwargs)

Returns an iterator over all found LDAP paths like the search() function above, but uses the user search filter (SEARCH_FILTER['userid']) unconditionally.

In contrary to plain search(), the first positional argument - if any are provided - is treated differently from the rest:
It is matched against each one of sAMAccountName, displayName and cn by building suitable conditions joined by 'OR'. The remaining positional arguments are treated normally.

get_first_entry(*args, **kwargs)

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

get_first_user(*args, **kwargs)

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

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.get_first_user(getpass.getuser())