ad-user-manager 0.1.0a11

Modern Active Directory user management tool with conflict resolution

AD User Manager

Modern Active Directory user management tool with conflict resolution, supporting both domain controller (PowerShell) and remote LDAP operations.

Features

• Dual Operation Modes: PowerShell on domain controllers for optimal performance, LDAP for remote connections
• Automatic Conflict Resolution: Intelligent username conflict detection and resolution
• Type-Safe Configuration: Pydantic-based configuration with validation
• Rich CLI Interface: Beautiful command-line interface with progress indicators
• Structured Logging: JSON and console logging with contextual information
• Modern Python: Built for Python 3.12+ with type hints and async support

Installation

pip install ad-user-manager

Quick Start

Domain Controller Mode (Recommended)

When running directly on a domain controller, the tool automatically uses PowerShell for optimal performance:

from ad_user_manager import ADConfig, DCServerConfig, create_ad_manager

# Configure for domain controller
config = ADConfig(
    server=DCServerConfig(
        connection_type="domain_controller",
        base_dn="CN=Users,DC=example,DC=com",
        use_current_credentials=True  # Use current user's AD credentials
    )
)

# Create user
with create_ad_manager(config) as manager:
    result = manager.create_user(
        username="jdoe",
        first_name="John",
        last_name="Doe",
        email="[e-mail]",
        resolve_conflicts=True
    )
    print(f"Created user: {result.username}")

LDAP Mode (Remote Connections)

For remote connections to Active Directory:

from ad_user_manager import ADConfig, LDAPServerConfig, create_ad_manager

# Configure for LDAP connection
config = ADConfig(
    server=LDAPServerConfig(
        connection_type="ldap",
        host="dc.example.com",
        port=389,
        use_ssl=False,
        bind_dn="CN=service-account,CN=Users,DC=example,DC=com",
        bind_password="your-password",
        base_dn="CN=Users,DC=example,DC=com"
    )
)

# Create user
with create_ad_manager(config) as manager:
    result = manager.create_user(
        username="jsmith",
        first_name="Jane",
        last_name="Smith",
        email="[e-mail]"
    )

CLI Usage

Create a User

# Domain controller mode
ad-user-manager create-user -u jdoe -f John -l Doe -e [e-mail]

# With conflict resolution
ad-user-manager create-user -u jdoe -f John -l Doe -e [e-mail] --resolve-conflicts

# Dry run mode
ad-user-manager create-user -u jdoe -f John -l Doe -e [e-mail] --dry-run

Search for a User

ad-user-manager search-user -u jdoe

Test Connection

ad-user-manager test-connection

Generate Username Suggestions

ad-user-manager suggest-usernames -f John -l Doe

Configuration

Environment Variables

# LDAP Configuration
export AD_CONNECTION_TYPE=ldap
export AD_HOST=dc.example.com
export AD_PORT=389
export AD_USE_SSL=false
export AD_BIND_DN="CN=service-account,CN=Users,DC=example,DC=com"
export AD_BIND_PASSWORD="your-password"
export AD_BASE_DN="CN=Users,DC=example,DC=com"

# Domain Controller Configuration
export AD_CONNECTION_TYPE=domain_controller
export AD_BASE_DN="CN=Users,DC=example,DC=com"
export AD_USE_CURRENT_CREDENTIALS=true

Configuration File

Create a .env file or use environment variables:

# For LDAP mode
AD_CONNECTION_TYPE=ldap
AD_HOST=dc.example.com
AD_BIND_DN=CN=service-account,CN=Users,DC=example,DC=com
AD_BIND_PASSWORD=your-password
AD_BASE_DN=CN=Users,DC=example,DC=com

# For DC mode
AD_CONNECTION_TYPE=domain_controller
AD_BASE_DN=CN=Users,DC=example,DC=com
AD_USE_CURRENT_CREDENTIALS=true

Advanced Features

Conflict Resolution

The tool automatically detects username conflicts and generates alternatives:

# Automatic conflict resolution
result = manager.create_user(
    username="jdoe",  # If exists, might become "jdoe1", "jdoe2", etc.
    first_name="John",
    last_name="Doe",
    email="[e-mail]",
    resolve_conflicts=True
)
print(f"Final username: {result.username}")
print(f"Conflicts resolved: {result.conflicts_resolved}")

Custom Attributes

result = manager.create_user(
    username="jdoe",
    first_name="John",
    last_name="Doe",
    email="[e-mail]",
    additional_attributes={
        "department": "Engineering",
        "title": "Software Developer",
        "telephoneNumber": "[phone]"
    }
)

Logging Configuration

config = ADConfig(
    server=your_server_config,
    log_level="DEBUG",  # DEBUG, INFO, WARNING, ERROR, CRITICAL
    log_format="json"   # "json" or "console"
)

Development

Setup

git clone https://github.com/your-org/ad-user-manager.git
cd ad-user-manager
pip install -e ".[dev]"

Running Tests

pytest

Code Quality

# Linting
ruff check .

# Formatting
black .

# Type checking
mypy .

Architecture

The project is organized into focused modules:

• models.py - Data models and configuration schemas
• powershell_manager.py - PowerShell-based AD operations (DC mode)
• ldap_manager.py - LDAP-based AD operations (remote mode)
• factory.py - Manager creation and auto-detection
• config.py - Configuration management
• validators.py - Input validation and conflict resolution
• exceptions.py - Custom exception hierarchy
• cli.py - Command-line interface
• utils.py - Utility functions

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues, feature requests, or questions:

1. Check the GitHub Issues
2. Create a new issue with detailed information
3. Include configuration (without sensitive data) and error messages