Welcome to ldap3-orm’s documentation!

Version

2.7.0

ldap3-orm is an object-relational mapper for LDAP data based on the ldap3 project

License

The ldap3-orm library is open source software released under the LGPL-3.0+ license (http://www.gnu.org/licenses/lgpl-3.0.html).

User model example

The following code creates a simple ORM model for a LDAP user entry:

from ldap3_orm import EntryBase, AttrDef


class User(EntryBase):
    dn = "uid={uid},{base_dn}"
    base_dn = "ou=People,dc=example,dc=com"
    object_classes = ["top", "inetUser", "inetOrgPerson"]

    username = AttrDef("uid")
    password = AttrDef("userPassword")
    fullname = AttrDef("cn")
    givenname = AttrDef("givenName")
    surname = AttrDef("sn")
    email = AttrDef("mail")

A User object can be instantiated using keyword arguments for each class attribute of type AttrDef:

>>> u = User(username="guest",
             password="{SSHA}oKJYPtoC+8mPBn/f47cSK5xWJuap183E",
             fullname="Guest User",
             givenname="Guest",
             surname="User",
             email="guest.user@example.com")
>>> u
DN: uid=guest,ou=People,dc=example,dc=com
    cn: Guest User
    givenName: Guest
    mail: guest.user@example.com
    sn: User
    uid: guest
    userPassword: {SSHA}oKJYPtoC+8mPBn/f47cSK5xWJuap183E

We can pass this object to an active ldap3_orm.Connection in order to create a new LDAP user entry:

>>> from ldap3_orm import Connection
>>> with Connection("ldap://ldap.example.com", "cn=directory manager",
                    "secret", auto_bind=True) as conn:
        conn.add(u.entry_dn, u.object_classes,
                 u.entry_get_attributes_dict)

Assuming the ORM model mentioned above has been stored in a file user.py an interactive ldap3-orm shell can be used to create further LDAP user entries using the following command:

$ ldap3-ipython -m user.py

ldap3-orm interactive shell (|version|, gcf02018)

The following convenience functions are available:

search  -> Search the connected LDAP.
add     -> Adds a new ``entry`` to the connected LDAP.
delete  -> Deletes an ``entry`` from the connected LDAP.

The current Connection can be accessed using 'conn'.


In [1]: u = User(username="guest",
   ...:          password="{SSHA}oKJYPtoC+8mPBn/f47cSK5xWJuap183E",
   ...:          fullname="Guest User",
   ...:          givenname="Guest",
   ...:          surname="User",
   ...:          email="guest.user@example.com")

In [2]: add(u)
Out[2]: True

or for searching the directory simply using Python operators:

In [3]: search((User.surname == "User") & (User.givenname == "Guest"))
Out[3]: True

In [4]: conn.entries
Out[4]: [DN: uid=guest,ou=People,dc=example,dc=com - STATUS: Read - READ
         TIME: 2018-03-15T14:32:00.369434]

Classes as well as instances derived from EntryBase provide self-descriptive representations:

In [5]: User
Out[5]:
OBJ : inetOrgPerson, top, inetUser
DN  : uid={uid},{base_dn}
MUST: email (mail), fullname (cn), givenname (givenName), password (userPassword), surname (sn), username (uid)
MAY :

In [6]: u
Out[6]:
DN: uid=guest,ou=People,dc=example,dc=com - STATUS: Writable - READ TIME: <never>
    cn: Guest User
    givenName: Guest
    mail: guest.user@example.com
    sn: User
    uid: guest
    userPassword: {SSHA}oKJYPtoC+8mPBn/f47cSK5xWJuap183E

The same code can be used in Jupyter when using the integrated ldap3-ipython kernel which provides the same functionality as the ldap3-orm shell mentioned above.

Indices and tables