tinyLDAP3 0.2.6

Tiny wrapper for Python ldap3 Package.

tinyLDAP3

Tiny wrapper for Python `ldap3` Package.

---

Table of Contents

1. About The Project
2. Installation
3. Usage
   • Instance Create
   • Object Detail
   • Object Read
   • Objects Search
   • Person Auth
4. Customization
5. License
6. Contact

---

About The Project

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam aliquam pretium mi quis laoreet.

(back to top)

Installation

Installation is as simple as:

pip install tinyLDAP3

(back to top)

Usage

Instance Create

Create a new instance of the tinyLDAP3Client class and assigns this object to the local variable ldap.

Optional Instance Attributes:
connect_timeout: int - Default value 10 (sec.)
receive_timeout: int - Default value 10 (sec.)

Don't store sensitive information in source code. For example use ".env" file.

from tinyLDAP3 import tinyLDAP3Client
from typing import Iterable

LDAP_USER_DN: str = "CN=Your-LDAP-Account,OU=_SpecialUsers,DC=example,DC=com"
LDAP_USER_PASSWORD: str  = "You%wILL#&neVeR!gUEss"
LDAP_SEARCH_BASE: str = "DC=example,DC=com"
LDAP_HOSTS: Iterable = ["10.10.10.2", "10.10.20.2", "10.10.30.2"]

if __name__ == "__main__":
    ldap = tinyLDAP3Client(
        user_dn=LDAP_USER_DN,
        user_pass=LDAP_USER_PASSWORD,
        search_base=LDAP_SEARCH_BASE,
        hosts=LDAP_HOSTS
    )

(back to top)

Object Detail

object_category - Three categories are expected: Computer, Group or Person.

Predefined list of returned attributes

• Category: Computer

  • cn

  • description

  • distinguishedName

  • lastLogon

  • logonCount

  • name

  • objectGUID

  • operatingSystem

  • operatingSystemVersion

  • sAMAccountName

  • sAMAccountType

  • servicePrincipalName

  • whenChanged

  • whenCreated

• Category: Group

  • cn

  • description

  • distinguishedName

  • mail

  • member

  • memberOf

  • name

  • objectGUID

  • sAMAccountName

  • sAMAccountType

  • whenChanged

  • whenCreated

• Category: Person

  • accountExpires

  • badPasswordTime

  • badPwdCount

  • cn

  • company

  • department

  • displayName

  • employeeID

  • employeeNumber

  • extensionAttribute12

  • extensionAttribute5

  • extensionAttribute6

  • extensionAttribute9

  • ipPhone

  • l

  • lastLogoff

  • lastLogon

  • lockoutTime

  • logonCount

  • mail

  • manager

  • memberOf

  • mobile

  • msDS-UserPasswordExpiryTimeComputed

  • msExchExtensionAttribute22

  • msExchExtensionAttribute23

  • msExchExtensionCustomAttribute1

  • msExchExtensionCustomAttribute2

  • objectGUID

  • pwdLastSet

  • sAMAccountName

  • sAMAccountType

  • servicePrincipalName

  • streetAddress

  • telephoneNumber

  • thumbnailPhoto

  • title

  • userAccountControl

  • userPrincipalName

  • whenChanged

  • whenCreated

Optional arguments:

• is_active: bool = False - Define the search scope: Active or All Users.
• returned_attrs_collection: Iterable[str] = None - Override the collection of predefined returned attributes.

Computer

ldap = ...
print("Result:", ldap.object_detail(
    object_category="computer",
    attr_name="sAMAccountName", 
    attr_value="value",
    returned_attrs_collection=["description", "sAMAccountName", "mail", "distinguishedName"]
))
# Result: {
#     'operatingSystem': None, 
#     'sAMAccountName': 'value', 
#     'whenCreated': datetime.datetime(...), 
#     'lastLogon': None, 
#     'cn': '...'
# }

Group

ldap = ...
print("Result:", ldap.object_detail(
    object_category="group",
    attr_name="sAMAccountName", 
    attr_value="value",
    returned_attrs_collection=["description", "sAMAccountName", "mail", "distinguishedName"]
))
# Result: {'mail': None, 'sAMAccountName': 'value', 'description': '...', 'distinguishedName': '...', 'cn': '...'}

Person

ldap = ...
# Unique value
print("Result:", ldap.object_detail(
    object_category="person",
    attr_name="sAMAccountName", 
    attr_value="unique_value",
    returned_attrs_collection=["sAMAccountName", "mail", "employeeNumber"]
))
# Result: {'mail': '...', 'sAMAccountName': 'unique_value', 'employeeNumber': '...'}

print("Result", ldap.object_detail(
    object_category="person",
    attr_name="sn",
    attr_value="value",
    returned_attrs_collection=["sAMAccountName", "mail", "employeeNumber"]
))
# WARNING:root:@ LDAP Object Detail @ - 'ObjectCategory: `person`, AttrName: `sn`, Value: `value`' \
# - More than one LDAP Object were found. Use attributes with unique values.
# Result: (
#     {'mail': '...', 'employeeNumber': '...', 'sAMAccountName': '...', 'sn': 'value'}, 
#     {'mail': '...', 'employeeNumber': '...', 'sAMAccountName': '...', 'sn': 'value'}
# )

(back to top)

Object Read

Reading object attributes by category and distinguishedName attribute value.

• returned_attrs_collection: Iterable[str] = None - Override the collection of returned attributes (Default: All attributes).

ldap = ...
print("Result:", ldap.object_read(
    object_category=["top", "person", "user"],
    dn="CN=Any-LDAP-Account,OU=_Users,DC=example,DC=com",
    returned_attrs_collection=[
        "objectClass", "description", "sAMAccountName", "name", "objectGUID"
    ]
))
# Result: {
#     'objectClass': ['top', 'person', 'organizationalPerson', 'user'], 
#     'description': None, 
#     'name': '...', 
#     'objectGUID': '{...-...-...-...-...}', 
#     'sAMAccountName': '...'
# }

(back to top)

Objects Search

object_category - Three categories are expected: Computer, Group or Person.

Predefined list of attributes for Person (User) search

• Category: Person

  • cn

  • employeeNumber

  • ipPhone

  • mail

  • mobile

  • sAMAccountName

Predefined list of returned attributes

• Category: Computer

  • cn

  • operatingSystem

  • operatingSystemVersion

  • whenChanged

  • whenCreated

• Category: Group

  • distinguishedName

  • mail

  • sAMAccountName

  • whenChanged

  • whenCreated

• Category: Person

  • department

  • displayName

  • employeeNumber

  • ipPhone

  • mail

  • mobile

  • sAMAccountName

  • title

  • userAccountControl

  • whenChanged

  • whenCreated

Category searching:

• Computer - wildcard: *value*
• Group - wildcard: *value*
• Person - wildcard: value*

Optional method arguments:

• order_by: str = "sAMAccountName" - Sorting by a specific attribute. Default value sAMAccountname. The attribute will be added automatically if it's missing from the collection of returned attributes.
• search_by_attrs_collection: Iterable[str] = None - Override the predefined list for Person (User) search.
• returned_attrs_collection: Iterable[str] = None - Override the predefined list of returned attributes.

Computer

ldap = ...
print("Result:", ldap.objects_search(
    object_category="computer",
    attr_value="value",
    returned_attrs_collection=["cn", "lastLogon", "operatingSystem"]
))
# Result: (
#     {'sAMAccountName': '...', 'cn': 'value', 'lastLogon': datetime.datetime(...), 'operatingSystem': '...'},
#     ...,
#     {'sAMAccountName': '...', 'cn': 'value', 'lastLogon': None, 'operatingSystem': '...'}, 
# )

Group

ldap = ...
print("Result:", ldap.objects_search(
    object_category="group",
    attr_value="value",
    returned_attrs_collection=["sAMAccountName", "distinguishedName"]
))
# Result: (
#     {'distinguishedName': 'CN=...', 'sAMAccountName': 'value'}, 
#     ...,
#     {'distinguishedName': 'CN=...', 'sAMAccountName': 'value'},
# )

Person

ldap = ...
print("Result", ldap.objects_search(
    object_category="person",
    attr_value="value",
    order_by="displayName",
    returned_attrs_collection=["mail"]
))
# Result: ({'mail': None, 'displayName': '...'}, ..., {'mail': '...', 'displayName': '...'}

(back to top)

Person Auth

login - Expected value of the userPrincipalName attribute.

Predefined list of returned attributes:

• "cn",
• "employeeNumber",
• "ipPhone",
• "mail",
• "mobile",
• "userPrincipalName",
• "sAMAccountName",

Optional method arguments:
returned_attrs_collection: Iterable[str] = None - Override the predefined list of returned attributes.

ldap = ...
print(ldap.person_auth(
    login="[e-mail]", 
    password="***",
))
# Result Auth Pass:
# (
#     True,
#     {
#         'ipPhone': '...', 
#         'userPrincipalName': '[e-mail]', 
#         'mobile': '...', 
#         'employeeNumber': '...', 
#         'mail': '...', 
#         'cn': '...', 
#         'sAMAccountName': '...'
#     }
# )
# Result Auth Failed:
# (
#     False, 
#     {
#         'result': 49,
#         'description': 'invalidCredentials',
#         'dn': '',
#         'message': '80090308: LdapErr: DSID-0C09056B, comment: AcceptSecurityContext error, data 52e, v4f7c\x00',
#         'referrals': None,
#         'saslCreds': None,
#         'type': 'bindResponse'
#     }
# )

(back to top)

Customization

Overriding _search_limit instance attributes:

from tinyLDAP3 import tinyLDAP3Client

class tinyLDAP3Custom(tinyLDAP3Client):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)

        self._search_limit = 1000

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Luarvick - [e-mail]

Project Link: https://github.com/luarvick/tinyLDAP3

(back to top)