User Management - UNITRONIX/BetterDesk GitHub Wiki

User Management

BetterDesk uses a four-tier RBAC (Role-Based Access Control) system for managing users.

Roles

Role Panel Access API Access Description
Admin ✅ Full ✅ Full Full server management, user CRUD, settings
Operator ✅ Limited ✅ Devices + connect Device management, remote connections, chat
Viewer ✅ Read-only ✅ Read-only Dashboard and device list viewing only
Pro ❌ None ✅ Full API API-only access, no panel login

Admin

  • Add/edit/delete users
  • View/manage all devices
  • Edit server settings
  • View audit logs
  • Reset passwords
  • Manage SSL certificates
  • Create/revoke API keys

Operator

  • View device list and details
  • Connect to devices (RustDesk URI handler)
  • Edit device notes and tags
  • Chat with end users
  • View own audit entries

Viewer

  • View dashboard statistics
  • View device list (read-only)
  • Cannot connect, edit, or delete devices
  • Cannot manage users or settings

Pro (API-Only)

  • No web panel access (login redirects with error)
  • Full REST API access with Bearer token authentication
  • Designed for automation, CI/CD, monitoring integrations
  • Can use all API endpoints except user management

Managing Users

Create a User

  1. Log in as Admin
  2. Go to Users page
  3. Click Add User
  4. Enter username, password, and select role
  5. Click Create

Edit a User

  1. Click the Edit button on a user row
  2. Change role, password, or status
  3. Click Save

Delete a User

  1. Click the Delete button on a user row
  2. Confirm deletion in the modal

Reset Admin Password

If you've lost the admin password:

# Linux
sudo ./betterdesk.sh
# Choose option 6 — Reset admin password

# Windows
.\betterdesk.ps1
# Choose option 6 — Reset admin password

# Manual reset (Node.js)
cd /opt/BetterDeskConsole
node reset-password.js

TOTP Two-Factor Authentication

BetterDesk supports TOTP (Time-based One-Time Password) for two-factor authentication, compatible with Google Authenticator, Authy, and other TOTP apps.

Enable 2FA

  1. Go to Settings → Change Password section
  2. Click Enable 2FA
  3. Scan the QR code with your authenticator app
  4. Enter the 6-digit verification code
  5. Save the recovery codes in a secure location

Login with 2FA

  1. Enter username and password
  2. When prompted, enter the 6-digit code from your authenticator
  3. The code is valid for 30 seconds (one time window tolerance)

Disable 2FA

  1. Go to Settings → Change Password section
  2. Click Disable 2FA
  3. Enter current password to confirm

Recovery

If you lose access to your authenticator:

  • Use one of the saved recovery codes (one-time use each)
  • Ask an admin to disable your 2FA from the Users page
  • Use the CLI password reset tool (resets both password and 2FA)

Pro User Setup

Pro users access BetterDesk entirely through the REST API.

Create a Pro User

  1. Log in as Admin
  2. Go to Users → Add User
  3. Set role to Pro
  4. Note the username and password

Authenticate as Pro

# Login and receive JWT token
curl -X POST http://your-server:21121/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "pro_user", "password": "secret"}'

# Response
{
  "access_token": "eyJhbGci...",
  "type": "access_token",
  "user": {
    "name": "pro_user",
    "role": "pro"
  }
}

Use the API

# List devices
curl http://your-server:21121/api/peers \
  -H "Authorization: Bearer eyJhbGci..."

# Get address book
curl http://your-server:21121/api/ab \
  -H "Authorization: Bearer eyJhbGci..."

See API Reference for all available endpoints.

Sessions & Security

Session Management

  • Sessions expire after 24 hours of inactivity
  • Session cookie: HttpOnly, Secure (when TLS enabled), SameSite=Lax
  • Session regeneration on login (prevents fixation attacks)

Password Requirements

  • Minimum 6 characters
  • Bcrypt hashing with auto-generated salt
  • Timing-safe authentication (pre-computed dummy hash for non-existent users)

Login Rate Limiting

  • 5 attempts per minute per IP
  • Applies to both password and TOTP verification
  • Audit log records all failed attempts

Audit Trail

All authentication events are logged:

  • Login success/failure with IP and user agent
  • 2FA verification attempts
  • Password changes
  • User creation/deletion
  • Role changes