{"id":8547,"library":"python-active-directory","title":"Python Active Directory Client Library","description":"Python-AD is an Active Directory client library designed for Python on UNIX/Linux systems. It provides a programmatic interface for performing various LDAP and Kerberos operations against Microsoft Active Directory domains. The library currently supports Python 3 environments, with its latest stable release being 2.0.1.","status":"active","version":"2.0.1","language":"en","source_language":"en","source_url":"https://github.com/theatlantic/python-active-directory","tags":["Active Directory","LDAP","authentication","Unix","Linux","Kerberos"],"install":[{"cmd":"pip install python-active-directory","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for LDAP communication with Active Directory.","package":"python-ldap","optional":false},{"reason":"Required by python-ldap for ASN.1 support.","package":"pyasn1","optional":false},{"reason":"Required by python-ldap for ASN.1 support.","package":"pyasn1-modules","optional":false}],"imports":[{"symbol":"Client","correct":"from activedirectory import Client"}],"quickstart":{"code":"import os\nfrom activedirectory import Client\n\n# Environment variables for sensitive information\nAD_SERVER = os.environ.get('AD_SERVER', 'your.ad.domain.com')\nAD_USERNAME = os.environ.get('AD_USERNAME', 'username@your.ad.domain.com')\nAD_PASSWORD = os.environ.get('AD_PASSWORD', 'your_password')\nAD_BASE_DN = os.environ.get('AD_BASE_DN', 'dc=your,dc=ad,dc=domain,dc=com')\n\ntry:\n    # Initialize the client, assuming typical LDAP over SSL (LDAPS) on port 636\n    # Note: The exact Client constructor might vary; this is an educated guess based on typical AD client libs.\n    # Consult official documentation or source code for precise constructor arguments.\n    ad_client = Client(\n        host=AD_SERVER,\n        username=AD_USERNAME,\n        password=AD_PASSWORD,\n        base_dn=AD_BASE_DN,\n        use_ssl=True, # Recommended for production\n        port=636\n    )\n\n    print(f\"Successfully connected to AD server: {AD_SERVER}\")\n\n    # Example: Search for a user (replace 'testuser' with an actual sAMAccountName)\n    # The library is expected to provide methods for common AD operations.\n    # This part is illustrative as specific methods are not detailed in public search results for 'theatlantic' fork.\n    # For a real implementation, you'd call a search_user or find_object method if available.\n    # For demonstration, let's assume a basic search capability for an object by its sAMAccountName.\n    # The actual implementation would require diving into the library's available methods.\n    print(f\"\\nAttempting to find user with sAMAccountName: {AD_USERNAME.split('@')[0]}\")\n    # In a real scenario, you'd use a dedicated search method like:\n    # user_found = ad_client.search_user(sAMAccountName=AD_USERNAME.split('@')[0])\n    # For a simple connection test without specific search methods, we'll just confirm connection.\n    # To perform actual searches, you would typically use methods exposed by the Client object, \n    # often involving LDAP filters.\n    \n    # Example of a generic search (hypothetical method):\n    # results = ad_client.search(base_dn=AD_BASE_DN, filter=f'(sAMAccountName={AD_USERNAME.split('@')[0]})')\n    # if results:\n    #     print(f\"Found user: {results[0].get('cn')}\")\n    # else:\n    #     print(\"User not found.\")\n\n    # If the Client object itself doesn't expose a direct 'search' method for this quickstart,\n    # we will just confirm the connection was successful.\n    print(\"Basic AD client initialized. Further operations depend on specific library methods.\")\n\nexcept Exception as e:\n    print(f\"Error connecting or interacting with Active Directory: {e}\")\n    print(\"Ensure AD_SERVER, AD_USERNAME, AD_PASSWORD, and AD_BASE_DN are correctly set.\")","lang":"python","description":"This quickstart demonstrates how to initialize the `Client` for connecting to Active Directory. It expects environment variables for the AD server, username (preferably UPN format), password, and base DN. The example assumes a secure connection using LDAPS on port 636, which is standard. Further interactions like searching for users would rely on methods exposed by the `Client` object, which are to be explored in the library's specific API documentation."},"warnings":[{"fix":"Upgrade your Python environment to Python 3.6 or newer, or pin your library version to `<2.0.0`.","message":"Version 2.0 of `python-active-directory` dropped support for Python 2. Projects requiring Python 2 must use an older major version (e.g., 1.x) or migrate to Python 3.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Implement paged results when performing extensive searches. The underlying `python-ldap` library provides `ldap.controls.SimplePagedResultsControl` for this purpose, which this library may wrap.","message":"Active Directory by default limits LDAP search results to 1,000 entries. Queries exceeding this limit will result in an error or truncated results if not handled with paged results.","severity":"gotcha","affected_versions":"All"},{"fix":"Always use the User Principal Name (UPN) format (e.g., `user@domain.com`) for the username. If experiencing referral issues, ensure your LDAP client configuration handles referrals correctly or disable them if appropriate for your environment.","message":"Incorrect username format (e.g., missing UPN suffix like `@domain.com`) or issues with LDAP referrals can lead to `ldap.INVALID_CREDENTIALS` errors even with correct passwords.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the username (often UPN format, e.g., 'user@domain.com') and password. Check if the Active Directory account is locked. If the problem persists, try disabling LDAP referrals in your client configuration if the library allows it, or ensure the client can follow referrals correctly.","cause":"The most common causes are incorrect username/password, an account locked out, or an issue with LDAP referrals (where the AD server redirects to another DC but the client fails to re-authenticate).","error":"ldap.INVALID_CREDENTIALS: {'info': '80090308: LdapErr: DSID-0C090334, comment: AcceptSecurityContext error, data 52e, vece'"},{"fix":"Modify your search query to be more specific, or implement paged search results. The underlying `python-ldap` library supports `ldap.controls.SimplePagedResultsControl` for handling large result sets. Refer to `python-ldap` documentation for details on implementing paged results if this library doesn't abstract it fully.","cause":"You attempted an LDAP search that returned more than 1,000 entries, hitting Active Directory's default maximum page size for unpaged searches.","error":"LDAPError: SIZE_LIMIT_EXCEEDED"}]}