ldap-cli 0.2.0__py3-none-any.whl

ldapc/ldap_client.py

@@ -0,0 +1,506 @@
+"""LDAP client module for ldapc.
+
+Provides the LdapClient class for managing LDAP connections and performing
+user and group searches against an LDAP directory server.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Self
+
+from ldap3 import (
+    ALL_ATTRIBUTES,
+    Connection,
+    Server,
+    Tls,
+    SUBTREE,
+    MODIFY_ADD,
+    MODIFY_DELETE,
+)
+from ldap3.core.exceptions import (
+    LDAPBindError,
+    LDAPExceptionError,
+    LDAPSocketOpenError,
+    LDAPSocketReceiveError,
+)
+
+from ldapc.exceptions import (
+    AuthenticationError,
+    ConnectionError,
+)
+
+LOG = logging.getLogger("ldapc")
+
+
+def _escape_filter_value(value: str) -> str:
+    """Escape special characters in an LDAP filter value per RFC 4515.
+
+    Characters with special meaning in LDAP filters are escaped to their
+    hex representation: \\XX.
+
+    Args:
+        value: The raw string to escape.
+
+    Returns:
+        The escaped string safe for use in LDAP filter assertions.
+    """
+    escaped = []
+    for char in value:
+        if char == "\\":
+            escaped.append("\\5c")
+        elif char == "*":
+            escaped.append("\\2a")
+        elif char == "(":
+            escaped.append("\\28")
+        elif char == ")":
+            escaped.append("\\29")
+        elif char == "\x00":
+            escaped.append("\\00")
+        else:
+            escaped.append(char)
+    return "".join(escaped)
+
+
+@dataclass
+class LdapEntry:
+    """A single LDAP directory entry.
+
+    Attributes:
+        dn: Distinguished name of the entry.
+        attributes: Attribute name to list of values mapping.
+    """
+
+    dn: str
+    attributes: dict[str, list[str]]
+
+
+class LdapClient:
+    """Manages LDAP connections and searches.
+
+    Establishes a TLS-secured connection to an LDAP server and provides
+    methods for searching user and group entries. Supports the context
+    manager protocol for automatic resource cleanup.
+
+    Example:
+        with LdapClient(host, username, password) as client:
+            users = client.search_users("john", "dc=example,dc=com")
+    """
+
+    def __init__(
+        self, host: str, username: str, password: str, timeout: int = 10,
+        skip_ssl_verify: bool = False,
+    ) -> None:
+        """Establish a TLS connection to the LDAP server.
+
+        Args:
+            host: LDAP server URL (e.g., ldaps://ldap.example.com:636).
+            username: Bind DN for authentication.
+            password: Bind password.
+            timeout: Connection timeout in seconds. Defaults to 10.
+            skip_ssl_verify: Skip TLS certificate verification. Defaults to False.
+
+        Raises:
+            ConnectionError: If the server is unreachable, the connection
+                times out, or TLS certificate verification fails.
+            AuthenticationError: If the bind credentials are rejected.
+        """
+        self._host = host
+        self._username = username
+        self._connection: Connection | None = None
+
+        use_ssl = host.lower().startswith("ldaps://")
+
+        try:
+            LOG.debug("Establishing connection to %s (ssl=%s, timeout=%ds)", host, use_ssl, timeout)
+            import ssl
+            validate = ssl.CERT_NONE if skip_ssl_verify else ssl.CERT_REQUIRED
+            tls = Tls(validate=validate)
+            server = Server(host, use_ssl=use_ssl, tls=tls, connect_timeout=timeout)
+            conn = Connection(
+                server,
+                user=username,
+                password=password,
+                auto_bind=True,
+                receive_timeout=timeout,
+            )
+        except LDAPBindError as exc:
+            raise AuthenticationError(
+                f"Authentication failed: invalid credentials for {username}"
+            ) from exc
+        except LDAPSocketOpenError as exc:
+            error_msg = str(exc).lower()
+            if "tls" in error_msg or "certificate" in error_msg or "ssl" in error_msg:
+                raise ConnectionError(
+                    f"TLS certificate verification failed for {host}"
+                ) from exc
+            raise ConnectionError(
+                f"Connection failed: unable to reach {host}"
+            ) from exc
+        except LDAPSocketReceiveError as exc:
+            raise ConnectionError(
+                f"Connection timed out after {timeout} seconds: {host}"
+            ) from exc
+        except (LDAPExceptionError, OSError) as exc:
+            error_msg = str(exc).lower()
+            if "timeout" in error_msg or "timed out" in error_msg:
+                raise ConnectionError(
+                    f"Connection timed out after {timeout} seconds: {host}"
+                ) from exc
+            if "tls" in error_msg or "certificate" in error_msg or "ssl" in error_msg:
+                raise ConnectionError(
+                    f"TLS certificate verification failed for {host}"
+                ) from exc
+            raise ConnectionError(
+                f"Connection failed: unable to reach {host}"
+            ) from exc
+
+        self._connection = conn
+        LOG.debug("Successfully bound to %s as %s", host, username)
+
+    def __enter__(self) -> Self:
+        """Enter the context manager.
+
+        Returns:
+            The LdapClient instance.
+        """
+        return self
+
+    def __exit__(self, exc_type: type | None, exc_val: Exception | None, exc_tb: object | None) -> None:
+        """Exit the context manager, closing the connection."""
+        self.close()
+
+    def search_users(self, search_term: str, base_dn: str) -> list[LdapEntry]:
+        """Search for user entries matching cn or uid (case-insensitive substring).
+
+        Args:
+            search_term: The term to search for in cn and uid fields.
+            base_dn: The base distinguished name to search under.
+
+        Returns:
+            A list of LdapEntry objects matching the search criteria.
+
+        Raises:
+            ConnectionError: If the search fails due to a connection issue.
+        """
+        escaped = _escape_filter_value(search_term)
+        search_filter = f"(&(objectClass=inetOrgPerson)(|(cn=*{escaped}*)(uid=*{escaped}*)))"
+        return self._search(search_filter, base_dn)
+
+    def search_groups(self, search_term: str, base_dn: str) -> list[LdapEntry]:
+        """Search for group entries matching cn (case-insensitive substring).
+
+        Args:
+            search_term: The term to search for in the cn field.
+            base_dn: The base distinguished name to search under.
+
+        Returns:
+            A list of LdapEntry objects matching the search criteria.
+
+        Raises:
+            ConnectionError: If the search fails due to a connection issue.
+        """
+        escaped = _escape_filter_value(search_term)
+        search_filter = f"(&(objectClass=posixGroup)(cn=*{escaped}*))"
+        return self._search(search_filter, base_dn)
+
+    def list_users(self, base_dn: str) -> list[LdapEntry]:
+        """List all user entries.
+
+        Args:
+            base_dn: The base distinguished name to search under.
+
+        Returns:
+            A list of all user LdapEntry objects.
+        """
+        search_filter = "(objectClass=inetOrgPerson)"
+        return self._search(search_filter, base_dn)
+
+    def list_groups(self, base_dn: str) -> list[LdapEntry]:
+        """List all group entries.
+
+        Args:
+            base_dn: The base distinguished name to search under.
+
+        Returns:
+            A list of all group LdapEntry objects.
+        """
+        search_filter = "(objectClass=posixGroup)"
+        return self._search(search_filter, base_dn)
+
+    def get_user(self, name: str, base_dn: str) -> list[LdapEntry]:
+        """Get a specific user by exact uid or cn.
+
+        Args:
+            name: Exact uid or cn to match.
+            base_dn: The base distinguished name to search under.
+
+        Returns:
+            A list of matching LdapEntry objects (typically 0 or 1).
+        """
+        escaped = _escape_filter_value(name)
+        search_filter = f"(&(objectClass=inetOrgPerson)(|(uid={escaped})(cn={escaped})))"
+        return self._search(search_filter, base_dn)
+
+    def get_group(self, name: str, base_dn: str) -> list[LdapEntry]:
+        """Get a specific group by exact cn.
+
+        Args:
+            name: Exact cn to match.
+            base_dn: The base distinguished name to search under.
+
+        Returns:
+            A list of matching LdapEntry objects (typically 0 or 1).
+        """
+        escaped = _escape_filter_value(name)
+        search_filter = f"(&(objectClass=posixGroup)(cn={escaped}))"
+        return self._search(search_filter, base_dn)
+
+    def add_user(self, name: str, base_dn: str, users_ou: str = "cn=users") -> None:
+        """Add a new user entry to the directory.
+
+        Creates an inetOrgPerson with uid and cn set to the given name.
+
+        Args:
+            name: The uid/cn for the new user.
+            base_dn: The base DN under which to create the user.
+            users_ou: The RDN of the users container. Defaults to "cn=users".
+
+        Raises:
+            ConnectionError: If the operation fails.
+        """
+        if self._connection is None:
+            raise ConnectionError(f"Connection failed: unable to reach {self._host}")
+
+        dn = f"uid={name},{users_ou},{base_dn}"
+        attributes = {
+            "objectClass": ["inetOrgPerson", "top"],
+            "uid": name,
+            "cn": name,
+            "sn": name,
+        }
+
+        LOG.debug("Adding user dn=%s", dn)
+
+        try:
+            self._connection.add(dn, attributes=attributes)
+        except (LDAPExceptionError, OSError) as exc:
+            raise ConnectionError(
+                f"Failed to add user '{name}': {exc}"
+            ) from exc
+
+        if not self._connection.result["description"] == "success":
+            msg = self._connection.result.get("message", self._connection.result.get("description", "unknown error"))
+            raise ConnectionError(f"Failed to add user '{name}': {msg}")
+
+    def add_group(self, name: str, base_dn: str, groups_ou: str = "cn=groups") -> None:
+        """Add a new group entry to the directory.
+
+        Creates a posixGroup with cn set to the given name.
+
+        Args:
+            name: The cn for the new group.
+            base_dn: The base DN under which to create the group.
+            groups_ou: The RDN of the groups container. Defaults to "cn=groups".
+
+        Raises:
+            ConnectionError: If the operation fails.
+        """
+        if self._connection is None:
+            raise ConnectionError(f"Connection failed: unable to reach {self._host}")
+
+        dn = f"cn={name},{groups_ou},{base_dn}"
+        attributes = {
+            "objectClass": ["posixGroup", "top"],
+            "cn": name,
+            "gidNumber": 0,
+        }
+
+        LOG.debug("Adding group dn=%s", dn)
+
+        try:
+            self._connection.add(dn, attributes=attributes)
+        except (LDAPExceptionError, OSError) as exc:
+            raise ConnectionError(
+                f"Failed to add group '{name}': {exc}"
+            ) from exc
+
+        if not self._connection.result["description"] == "success":
+            msg = self._connection.result.get("message", self._connection.result.get("description", "unknown error"))
+            raise ConnectionError(f"Failed to add group '{name}': {msg}")
+
+    def delete_user(self, name: str, base_dn: str, users_ou: str = "cn=users") -> None:
+        """Delete a user entry from the directory.
+
+        Args:
+            name: The uid of the user to delete.
+            base_dn: The base DN under which the user exists.
+            users_ou: The RDN of the users container. Defaults to "cn=users".
+
+        Raises:
+            ConnectionError: If the operation fails.
+        """
+        if self._connection is None:
+            raise ConnectionError(f"Connection failed: unable to reach {self._host}")
+
+        dn = f"uid={name},{users_ou},{base_dn}"
+        LOG.debug("Deleting user dn=%s", dn)
+
+        try:
+            self._connection.delete(dn)
+        except (LDAPExceptionError, OSError) as exc:
+            raise ConnectionError(
+                f"Failed to delete user '{name}': {exc}"
+            ) from exc
+
+        if not self._connection.result["description"] == "success":
+            msg = self._connection.result.get("message", self._connection.result.get("description", "unknown error"))
+            raise ConnectionError(f"Failed to delete user '{name}': {msg}")
+
+    def delete_group(self, name: str, base_dn: str, groups_ou: str = "cn=groups") -> None:
+        """Delete a group entry from the directory.
+
+        Args:
+            name: The cn of the group to delete.
+            base_dn: The base DN under which the group exists.
+            groups_ou: The RDN of the groups container. Defaults to "cn=groups".
+
+        Raises:
+            ConnectionError: If the operation fails.
+        """
+        if self._connection is None:
+            raise ConnectionError(f"Connection failed: unable to reach {self._host}")
+
+        dn = f"cn={name},{groups_ou},{base_dn}"
+        LOG.debug("Deleting group dn=%s", dn)
+
+        try:
+            self._connection.delete(dn)
+        except (LDAPExceptionError, OSError) as exc:
+            raise ConnectionError(
+                f"Failed to delete group '{name}': {exc}"
+            ) from exc
+
+        if not self._connection.result["description"] == "success":
+            msg = self._connection.result.get("message", self._connection.result.get("description", "unknown error"))
+            raise ConnectionError(f"Failed to delete group '{name}': {msg}")
+
+    def add_user_to_group(self, user: str, group: str, base_dn: str,
+                          users_ou: str = "cn=users", groups_ou: str = "cn=groups") -> None:
+        """Add a user to a group's member list.
+
+        Args:
+            user: The uid of the user to add.
+            group: The cn of the group.
+            base_dn: The base DN.
+            users_ou: The RDN of the users container.
+            groups_ou: The RDN of the groups container.
+
+        Raises:
+            ConnectionError: If the operation fails.
+        """
+        if self._connection is None:
+            raise ConnectionError(f"Connection failed: unable to reach {self._host}")
+
+        group_dn = f"cn={group},{groups_ou},{base_dn}"
+        user_dn = f"uid={user},{users_ou},{base_dn}"
+
+        LOG.debug("Adding %s to group %s", user_dn, group_dn)
+
+        try:
+            self._connection.modify(group_dn, {"memberUid": [(MODIFY_ADD, [user])]})
+        except (LDAPExceptionError, OSError) as exc:
+            raise ConnectionError(
+                f"Failed to add user '{user}' to group '{group}': {exc}"
+            ) from exc
+
+        if not self._connection.result["description"] == "success":
+            msg = self._connection.result.get("message", self._connection.result.get("description", "unknown error"))
+            raise ConnectionError(f"Failed to add user '{user}' to group '{group}': {msg}")
+
+    def remove_user_from_group(self, user: str, group: str, base_dn: str,
+                              users_ou: str = "cn=users", groups_ou: str = "cn=groups") -> None:
+        """Remove a user from a group's member list.
+
+        Args:
+            user: The uid of the user to remove.
+            group: The cn of the group.
+            base_dn: The base DN.
+            users_ou: The RDN of the users container.
+            groups_ou: The RDN of the groups container.
+
+        Raises:
+            ConnectionError: If the operation fails.
+        """
+        if self._connection is None:
+            raise ConnectionError(f"Connection failed: unable to reach {self._host}")
+
+        group_dn = f"cn={group},{groups_ou},{base_dn}"
+
+        LOG.debug("Removing %s from group %s", user, group_dn)
+
+        try:
+            self._connection.modify(group_dn, {"memberUid": [(MODIFY_DELETE, [user])]})
+        except (LDAPExceptionError, OSError) as exc:
+            raise ConnectionError(
+                f"Failed to remove user '{user}' from group '{group}': {exc}"
+            ) from exc
+
+        if not self._connection.result["description"] == "success":
+            msg = self._connection.result.get("message", self._connection.result.get("description", "unknown error"))
+            raise ConnectionError(f"Failed to remove user '{user}' from group '{group}': {msg}")
+
+    def close(self) -> None:
+        """Unbind and close the LDAP connection.
+
+        Safe to call multiple times; subsequent calls are no-ops.
+        """
+        if self._connection is not None:
+            try:
+                self._connection.unbind()
+            except (LDAPExceptionError, OSError):
+                pass
+            self._connection = None
+
+    def _search(self, search_filter: str, base_dn: str) -> list[LdapEntry]:
+        """Execute an LDAP search and return results as LdapEntry objects.
+
+        Args:
+            search_filter: The LDAP filter string.
+            base_dn: The base DN to search under.
+
+        Returns:
+            A list of LdapEntry objects.
+
+        Raises:
+            ConnectionError: If the search fails due to a connection issue.
+        """
+        if self._connection is None:
+            raise ConnectionError(
+                f"Connection failed: unable to reach {self._host}"
+            )
+
+        LOG.debug("Searching base_dn=%s filter=%s", base_dn, search_filter)
+
+        try:
+            self._connection.search(
+                search_base=base_dn,
+                search_filter=search_filter,
+                search_scope=SUBTREE,
+                attributes=[ALL_ATTRIBUTES],
+            )
+        except (LDAPExceptionError, OSError) as exc:
+            raise ConnectionError(
+                f"Connection failed: unable to reach {self._host}"
+            ) from exc
+
+        entries: list[LdapEntry] = []
+        for entry in self._connection.entries:
+            attrs: dict[str, list[str]] = {}
+            for attr_name in entry.entry_attributes:
+                values = entry[attr_name].values
+                attrs[attr_name] = [str(v) for v in values]
+            entries.append(LdapEntry(dn=str(entry.entry_dn), attributes=attrs))
+
+        return entries