Matrix LDAP User Prune

This Python script scans all users in a specified Matrix instance, checks each user against an LDAP directory, and performs the following actions:

• Deletes the Matrix user if they do not exist in LDAP
• Deactivates the Matrix user if a designated LDAP attribute for deactivation is present and set to "TRUE"

Installation

Prerequisites

• Linux server with Python 3.8 or higher
• Access to Matrix homeserver with admin privileges
• LDAP server access
• Git (for cloning the repository)

Production Setup

1. Clone the Repository

git clone https://github.com/verdigado/matrix-ldap-user-prune.git
cd matrix-ldap-user-prune

2. Run Setup Script

The setup script will create a virtual environment, install dependencies, and create a configuration template:

chmod +x setup.sh
./setup.sh

3. Configure the Application

Edit the configuration file with your Matrix and LDAP settings:

cp config.yaml.dist config.yaml
nano config.yaml  # or use your preferred editor

Update the following sections:

• Matrix: Set your homeserver URL and admin token
• LDAP: Configure your LDAP server connection details
• Sync: Adjust sync behavior and logging preferences

4. Test the Configuration

Run a dry-run to test your configuration:

source venv/bin/activate
python3 matrix-ldap-user-prune.py --dry-run --verbose

5. Set Up Systemd Service (Optional)

For automated execution, create a systemd service:

sudo tee /etc/systemd/system/matrix-ldap-user-prune.service > /dev/null <<EOF
[Unit]
Description=Matrix LDAP User Prune
After=network.target

[Service]
Type=oneshot
User=matrix-sync
WorkingDirectory=/opt/matrix-ldap-user-prune
Environment=PATH=/opt/matrix-ldap-user-prune/venv/bin
ExecStart=/opt/matrix-ldap-user-prune/venv/bin/python3 matrix-ldap-user-prune.py
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# Create timer for periodic execution
sudo tee /etc/systemd/system/matrix-ldap-user-prune.timer > /dev/null <<EOF
[Unit]
Description=Run Matrix LDAP User Prune every hour
Requires=matrix-ldap-user-prune.service

[Timer]
OnCalendar=hourly
Persistent=true

[Install]
WantedBy=timers.target
EOF

# Enable and start the timer
sudo systemctl daemon-reload
sudo systemctl enable matrix-ldap-user-prune.timer
sudo systemctl start matrix-ldap-user-prune.timer

6. Manual Installation (Alternative)

If you prefer manual installation without the setup script:

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Upgrade pip and install dependencies
pip install --upgrade pip
pip install -e .

# Copy and edit configuration
cp config.yaml.dist config.yaml
# Edit config.yaml with your settings

Usage

Basic Commands

# Activate virtual environment
source venv/bin/activate

# Show help
python3 matrix-ldap-user-prune.py --help

# Dry run (recommended first)
python3 matrix-ldap-user-prune.py --dry-run --verbose

# Production run
python3 matrix-ldap-user-prune.py --config config.yaml

# Run with custom config
python3 matrix-ldap-user-prune.py --config /path/to/custom-config.yaml

Development Setup

Setup Element/Matrix

Init Synapse config (first time only)

docker run -it --rm \
  -v "$(pwd)/data/synapse:/data" \
  -e SYNAPSE_SERVER_NAME=localhost \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest generate

Start Containers

docker compose up -d

Create Admin User

Enter Container

docker compose exec synapse bash

Execute new user command

register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008 -u admin -p password -a

Create API Token

curl -X POST http://localhost:8008/_matrix/client/r0/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "admin",
    "password": "password"
  }'

Access

• Synapse API: http://localhost:8008
• Element Web UI: http://localhost:8080