Adding and Removing MODX Users | OpsBlu Docs

Adding and Removing MODX Users

How to add and remove team members in Modx. Covers invitation workflows, role assignment, access revocation, and user lifecycle management for analytics.

Comprehensive guide for creating, managing, and removing user accounts in MODX CMS, including both MODX Revolution and MODX Classic.

Prerequisites

To manage users, you must have:

  • Administrator access to MODX Manager
  • Understanding of MODX user groups and roles
  • Access to MODX Manager backend

Required permissions:

  • view_users - View user list
  • save_user - Create/edit users
  • remove_user - Delete users
  • usergroup_edit - Manage user groups

MODX versions covered:

  • MODX Revolution 2.x and 3.x (primary focus)
  • MODX Classic (legacy, basic coverage)

Understanding MODX User Structure

Users, Roles, and User Groups

MODX uses a three-tier permission system:

User (Individual account)
├── User Groups (Categories/Teams)
│   └── Roles (Position in group)
│       └── Access Policies (Permissions)
└── Context Access (Which sites/contexts)

User:

  • Individual account with credentials
  • Unique username and email
  • Belongs to one or more user groups

User Group:

  • Collection of users (e.g., "Administrators", "Editors")
  • Defines group membership
  • Can have multiple roles

Role:

  • Position within user group (e.g., "Super User", "Member")
  • Hierarchical authority level
  • Numerical ranking (0 = highest authority)

Access Policy:

  • Defines specific permissions
  • Attached to user group + role combination
  • Controls what users can do

Adding Users to MODX

Method 1: Manager Interface (GUI)

Best for: Adding individual users manually

Step 1: Access User Management

MODX Revolution:

Manager → Security → Manage Users

Or use top menu:

Security → Users

Step 2: Create New User

  1. Click "New User" button (top right)
  2. User Information tab:

Required fields:

  • Username: Unique login identifier (alphanumeric, underscores allowed)
    • Example: john.doe or jdoe
    • Cannot be changed after creation
  • Full Name: Display name
    • Example: John Doe
  • Email: User's email address (must be unique)
    • Example: john@company.com
  • Password: Initial password (user should change)
    • Use "Generate Password" for strong password
    • Or create custom password

Optional fields:

  • Active: Check to enable account
  • Blocked: Uncheck (checked = account disabled)
  • Photo: User avatar
  • Phone: Contact number
  • Mobile Phone: Mobile contact
  • Date of Birth: User birthday
  • Gender: User gender
  • Country: User location
  • State: User state/province
  • ZIP: Postal code
  • Website: User website URL
  • Comment: Internal notes about user

Step 3: Set Password Options

Password settings:

  • Password must be reset: Force password change on first login
  • Blocked: Block user account
  • Activated: Account is active (should be checked)

Email notifications:

  • Send password email: Email credentials to user
  • Send activation email: Email account activation link

Best practice: Enable "Password must be reset" and "Send password email" for new users.

Step 4: Assign User Groups

User Groups tab:

  1. Click "Add User to Group"
  2. Select User Group from dropdown
  3. Select Role for this group
    • Super User (authority 0)
    • Administrator (authority 9999)
    • Member (authority 9999)
    • Custom role
  4. Save

Multiple groups:

  • Users can belong to multiple groups
  • Different role in each group
  • Permissions are cumulative

Example assignment:

User: John Doe
├── User Group: Administrators (Role: Member)
└── User Group: Content Editors (Role: Super User)

Step 5: Set Context Access

Access Permissions tab:

  1. Click "Add Context Access"
  2. Select Context (web, mgr, etc.)
  3. Select User Group (must be assigned first)
  4. Select Minimum Role required
  5. Select Access Policy
    • AdministratorPolicy
    • ContentEditorPolicy
    • Custom policy
  6. Save

Common contexts:

  • web - Frontend website access
  • mgr - Manager backend access

Step 6: Save User

  1. Review all settings
  2. Click "Save" button
  3. User account created

Method 2: Programmatic User Creation

Best for: Bulk user creation, migrations, automation

Basic User Creation (PHP)

<?php
// Create user programmatically
$user = $modx->newObject('modUser');
$user->set('username', 'johndoe');
$user->set('active', 1);
$user->set('password', 'SecurePassword123!'); // Will be hashed automatically

// Create user profile
$profile = $modx->newObject('modUserProfile');
$profile->set('fullname', 'John Doe');
$profile->set('email', 'john@example.com');
$profile->set('phone', '555-1234');
$profile->set('blocked', 0);
$profile->set('internalKey', $user->get('id'));

// Associate profile with user
$user->addOne($profile);

// Save user
if ($user->save()) {
    echo "User created successfully: ID " . $user->get('id');
} else {
    echo "Error creating user";
}

Add User to Group

<?php
// Add user to Administrator group
$userGroup = $modx->getObject('modUserGroup', array('name' => 'Administrator'));
$role = $modx->getObject('modUserGroupRole', array('name' => 'Member'));

if ($userGroup && $role) {
    $membership = $modx->newObject('modUserGroupMember');
    $membership->set('user_group', $userGroup->get('id'));
    $membership->set('member', $user->get('id'));
    $membership->set('role', $role->get('id'));
    $membership->save();
}

Complete User Setup

<?php
// Complete user creation with groups and context access
function createMODXUser($modx, $username, $email, $fullname, $password, $groups = array()) {
    // Create user
    $user = $modx->newObject('modUser');
    $user->set('username', $username);
    $user->set('active', 1);

    // Hash password
    $user->set('password', $password);
    $user->save(); // Save to hash password

    // Create profile
    $profile = $modx->newObject('modUserProfile');
    $profile->set('fullname', $fullname);
    $profile->set('email', $email);
    $profile->set('blocked', 0);
    $profile->set('internalKey', $user->get('id'));
    $user->addOne($profile);

    // Save user with profile
    if (!$user->save()) {
        return false;
    }

    // Add to user groups
    foreach ($groups as $groupName => $roleName) {
        $userGroup = $modx->getObject('modUserGroup', array('name' => $groupName));
        $role = $modx->getObject('modUserGroupRole', array('name' => $roleName));

        if ($userGroup && $role) {
            $membership = $modx->newObject('modUserGroupMember');
            $membership->set('user_group', $userGroup->get('id'));
            $membership->set('member', $user->get('id'));
            $membership->set('role', $role->get('id'));
            $membership->save();
        }
    }

    return $user->get('id');
}

// Usage
$userId = createMODXUser(
    $modx,
    'johndoe',
    'john@example.com',
    'John Doe',
    'SecurePassword123!',
    array(
        'Administrator' => 'Member',
        'Content Editors' => 'Super User'
    )
);

Method 3: Snippet-Based Registration

Best for: Frontend user registration forms

Using Login Package

Install Login package:

Manager → Extras → Installer
Search: "Login"
Download and install

Create registration form:

<!-- Frontend registration page -->
[[!Register?
    &submitVar=`registerbtn`
    &activationEmailSubject=`Activate your account`
    &activationEmailTpl=`myActivationEmailTpl`
    &usergroups=`Registered Users`
    &validate=`nospam:blank,
        username:required:minLength=^3^,
        password:required:minLength=^8^,
        password_confirm:password_confirm=^password^,
        email:required:email,
        fullname:required`
    &placeholderPrefix=`reg.`
]]

<form action="[[~[[*id]]]]" method="post">
    <label>Username: <input type="text" name="username" value="[[+reg.username]]" /></label>
    <label>Email: <input type="email" name="email" value="[[+reg.email]]" /></label>
    <label>Full Name: <input type="text" name="fullname" value="[[+reg.fullname]]" /></label>
    <label>Password: <input type="password" name="password" /></label>
    <label>Confirm Password: <input type="password" name="password_confirm" /></label>
    <input type="hidden" name="nospam" value="" />
    <button type="submit" name="registerbtn" value="Register">Register</button>
</form>

Managing Existing Users

Edit User Information

Via Manager:

  1. Security → Manage Users
  2. Right-click user → Edit User
    • Or click username
  3. Modify fields as needed
  4. Save

Change User Groups

Add to additional group:

  1. Edit user
  2. User Groups tab
  3. Click "Add User to Group"
  4. Select group and role
  5. Save

Remove from group:

  1. Edit user
  2. User Groups tab
  3. Right-click group membership
  4. Select "Remove"
  5. Save

Activate/Deactivate User

Temporary deactivation:

  1. Edit user
  2. Uncheck "Active"
    • Or check "Blocked"
  3. Save

Effect: User cannot log in but account preserved.

Reactivation:

  1. Edit user
  2. Check "Active"
  3. Uncheck "Blocked"
  4. Save

Change User Password

As administrator:

  1. Edit user
  2. Settings tab
  3. Password field: Enter new password
  4. Confirm Password: Re-enter password
  5. Save

Force password reset:

  • Check "Password must be reset"
  • User forced to change password on next login

Removing Users from MODX

Pre-Removal Checklist

Before deleting a user:

  • Check content ownership: Resources created by user
  • Review activity: Recent changes made
  • Backup user data: Export if needed
  • Reassign ownership: Transfer important content
  • Document removal: Reason and date
  • Verify no active sessions: Log user out

Method 1: Delete via Manager

Step 1: Access User List

Manager → Security → Manage Users

Step 2: Delete User

Option A: Right-click menu

  1. Right-click user in list
  2. Select "Delete User"
  3. Confirmation dialog:
    Are you sure you want to delete this user?
This cannot be undone.
  4. Click "Yes" to confirm

Option B: Edit screen

  1. Click username to edit
  2. Click "Delete" button (top right)
  3. Confirm deletion

What Gets Deleted

Removed:

  • User account
  • User profile
  • User group memberships
  • User settings
  • Session data

Preserved:

  • Resources created by user (not deleted)
  • Content remains attributed to user ID
  • Activity logs

Method 2: Programmatic Deletion

<?php
// Delete user by ID
$userId = 123;
$user = $modx->getObject('modUser', $userId);

if ($user) {
    // Remove user
    if ($user->remove()) {
        echo "User deleted successfully";
    } else {
        echo "Error deleting user";
    }
} else {
    echo "User not found";
}

// Delete user by username
$username = 'johndoe';
$user = $modx->getObject('modUser', array('username' => $username));

if ($user) {
    $user->remove();
}

Reassign Content Before Deletion

<?php
// Reassign user's resources to another user
$oldUserId = 123; // User being deleted
$newUserId = 1;   // User to receive content (usually admin)

// Get all resources by user
$resources = $modx->getCollection('modResource', array('createdby' => $oldUserId));

foreach ($resources as $resource) {
    $resource->set('createdby', $newUserId);
    $resource->set('editedby', $newUserId);
    $resource->save();
}

// Now safe to delete user
$user = $modx->getObject('modUser', $oldUserId);
$user->remove();

Method 3: Disable Instead of Delete

Preferred approach: Block user instead of deleting

Benefits:

  • Preserves audit trail
  • Content ownership maintained
  • Can be reactivated
  • Safer than permanent deletion

Implementation:

  1. Edit user
  2. Check "Blocked"
  3. Uncheck "Active"
  4. Add comment: "Deactivated [date] - [reason]"
  5. Save

Special Scenarios

Removing Administrator Users

Cannot delete last administrator:

  • MODX prevents deletion of sole admin
  • Must have at least one active admin

Process:

  1. Ensure another admin exists
  2. Verify new admin can access Manager
  3. Then delete old admin account

Emergency Access Revocation

Security incident:

Immediate actions:

  1. Block user account (Security → Users → Edit → Block)
  2. Change password to random string
  3. Remove from user groups
  4. Kill active sessions:
    <?php
// Clear user's active sessions
$modx->removeAllEventListener($userId);
  5. Review recent activity:
    • Check Manager logs
    • Review resource changes
    • Audit access logs

Post-incident:

  • Full security audit
  • Review all user permissions
  • Update security policies
  • Document incident

Bulk User Deletion

Delete multiple inactive users:

<?php
// Delete users inactive for 90+ days
$threshold = strtotime('-90 days');

$c = $modx->newQuery('modUser');
$c->leftJoin('modUserProfile', 'Profile');
$c->where(array(
    'Profile.lastlogin:>=' => 0,
    'Profile.lastlogin:<' => $threshold,
    'active' => 0
));

$users = $modx->getCollection('modUser', $c);

foreach ($users as $user) {
    // Skip user ID 1 (super admin)
    if ($user->get('id') == 1) continue;

    echo "Deleting user: " . $user->get('username') . "\n";
    $user->remove();
}

MODX Classic (Legacy)

Add User (Classic)

Manager → Tools → User Management → New User

Simpler interface:

  • Username, Password, Email
  • Web Access (frontend)
  • Manager Access (backend)
  • Admin status
  • User Groups

Delete User (Classic)

Manager → Tools → User Management
Right-click user → Delete
Confirm deletion

Best Practices

Adding Users

Security first:

  • ✓ Strong password requirements (min 12 chars)
  • ✓ Force password reset on first login
  • ✓ Assign minimum necessary permissions
  • ✓ Use user groups, not individual permissions
  • ✓ Document user purpose and access level
  • ✗ Don't use admin account for regular users
  • ✗ Don't share accounts

Onboarding checklist:

  • Create user account
  • Assign to appropriate user groups
  • Set context access
  • Email credentials
  • Provide Manager training
  • Document responsibilities

Removing Users

Clean offboarding:

  • ✓ Deactivate same day as departure
  • ✓ Reassign critical content
  • ✓ Export user data if needed
  • ✓ Document removal reason
  • ✓ Review recent activity
  • ✗ Don't delay removal
  • ✗ Don't delete without backup

Audit trail:

  • Log removal date
  • Note who performed removal
  • Document reason
  • Keep records for compliance

Troubleshooting

Cannot Create User - Username Exists

Error: "Username already exists"

Solutions:

  • Choose different username
  • Check if user was previously deleted
  • Search users list thoroughly

User Cannot Log In After Creation

Check:

  1. Active checkbox is checked
  2. Blocked checkbox is unchecked
  3. Password is correct
  4. User has context access to mgr
  5. User belongs to appropriate group

Fix:

  • Edit user and verify settings
  • Reset password
  • Check user group assignments

Deleted User's Content Missing

MODX doesn't delete content when removing users.

If content appears missing:

  • Check user ID association
  • Search by user ID in resources
  • Content may be unpublished
  • Check deleted resources (if trash enabled)

Next Steps

Back to top