Establishing connections¶
Before performing any LDAP operation, a client must establish a connection to the server. LDAP supports different transport security models, ranging from fully encrypted TLS sessions to unencrypted plaintext connections. Some deployments require STARTTLS to upgrade an existing unencrypted connection to a secure one, while others rely on direct TLS from the start.
The following examples illustrate:
Regular connection — opening a standard LDAP session without additional security layers.
STARTTLS — initiating an unencrypted connection, then upgrading to TLS.
Direct TLS — connecting to the server using TLS from the outset.
Unencrypted plaintext connection — for testing or in trusted networks only; not recommended for production.
Connection options — configuring and retrieving LDAP connection parameters.
Each example assumes the server’s hostname, port, and security requirements are known.
Establish connection¶
from freeiam import ldap
from freeiam.ldap.constants import TLSRequireCert
TIMEOUT = 30 # set a usefull default timeout!
async def ldap_connection_example():
"""Basic LDAP connection handling."""
# you can just do everything manually, or with a context manager, see next example
connection = ldap.Connection('ldap://localhost:389', timeout=TIMEOUT)
connection.connect()
await connection.bind('cn=admin,dc=freeiam,dc=org', 'iamfree')
# you can also reconnect!
connection.reconnect()
# or unbind
await connection.unbind()
# and disconnect
connection.disconnect()
Using START TLS¶
async def ldap_start_tls_connection_example():
"""A connection to the LDAP server using StartTLS (bound to the admin account)"""
# connect via START TLS to the plaintext port
async with ldap.Connection('ldap://localhost:389', timeout=TIMEOUT) as conn:
conn.set_tls(
ca_certfile='/path/to/ca.crt',
certfile='/path/to/cert.crt',
require_cert=TLSRequireCert.Hard, # allow no self signed? be strict?!
)
await conn.start_tls()
await conn.bind('cn=admin,dc=freeiam,dc=org', 'iamfree')
...
Using TLS¶
async def ldaps_secure_connection_example():
"""A connection to the LDAP server using TLS (bound to the admin account)"""
# connect via TLS encryption to the TLS port
async with ldap.Connection('ldap://localhost:389', timeout=TIMEOUT) as conn:
conn.set_tls(
ca_certfile='/path/to/ca.crt',
certfile='/path/to/cert.crt',
require_cert=TLSRequireCert.Never, # be unstrict (verify=False)
)
await conn.bind('cn=admin,dc=freeiam,dc=org', 'iamfree')
...
Unencrypted plaintext conncetion¶
async def ldap_plaintext_connection_example():
"""A connection to the LDAP server using plaintext (bound to the admin account)"""
# connect via plaintext (unsafe!)
async with ldap.Connection('ldap://localhost:389', timeout=TIMEOUT) as conn:
await conn.bind('cn=admin,dc=freeiam,dc=org', 'iamfree')
...
Connection options¶
from freeiam import ldap
from freeiam.ldap.constants import Dereference, Version
async def ldap_set_connection_options_example():
"""Set various connection options easily"""
async with ldap.Connection('ldap://localhost:389') as conn:
# you can't remeber the constant names?
# or you don't want to type `conn.set_option(Option.Foo, value)`?
# Limit on waiting for any response, in seconds.
conn.timelimit = 30
# Limit on waiting for a network response, in seconds.
conn.network_timeout = 30
conn.follow_referrals = True
# Controls whether aliases are automatically dereferenced.
conn.dereference = Dereference.Always
# Set the protocol version
assert conn.protocol_version == Version.LDAPV3
conn.protocol_version = Version.LDAPV3
# Limit on size of message to receive from server.
conn.sizelimit = 50