Skip to content

Users & Roles ​

DATAZONE Control features a role-based access control system. Users are assigned roles that define specific permissions for modules and functions.

Managing Users ​

Access user management via Settings > Users.

Creating a User ​

  1. Click Add User
  2. Enter the following information:
FieldDescription
UsernameUnique login name
Display NameName shown in the interface
EmailEmail address
PasswordInitial password
RolesAssign one or more roles

Editing a User ​

  1. Click on a user in the list
  2. Modify the desired fields
  3. Save the changes

Deactivating a User ​

In the user list, click the Deactivate icon (crossed-out person) in the actions column. Clicking again (icon with a check mark) reactivates the user.

Deactivation takes effect immediately: from the next request on, the blocked user is locked out of all access – web UI, API key and MCP token. The user and all associated data remain in the system (e.g., for audit purposes).

Deactivate instead of delete

Always use Deactivate rather than delete. This keeps the audit trail (who did what) intact and preserves referenced data (tasks, script executions, schedules).

Note: You cannot deactivate yourself.

Viewing a user's permissions ​

Since v3.63.0 the key icon in the actions column opens Permissions of …. It shows everything the user may do, combined from all roles:

  • Administrator: yes if a role has * or both "Manage users" and "Manage roles". The user may then do everything, including what no role grants individually.
  • Customer binding: a customer-bound user only sees hosts, jobs and data of that customer. Admin areas stay locked even with the permission.
  • Roles, and below them the number of granted permissions per module.
  • General permissions and a permission × module table. Granted only hides what the user may not do. Hover a check mark to see which role grants it.

The overview is read-only. Change permissions through the roles.

Automatic Logout (Session Timeout) ​

Web sessions expire automatically after a period of inactivity; the user then has to log in again. As long as the user is actively working, the session stays alive (sliding expiry) – on inactivity (e.g. overnight) it ends.

  • Default: 8 hours of inactivity.
  • Configurable: environment variable SESSION_INACTIVITY_MINUTES in .env (value in minutes), then restart the backend.
  • Affects web logins only; MCP tokens (API/automation) are not affected.

One-time re-login after the update

After this feature is deployed, all existing sessions become invalid once – every user has to log in again a single time.

Managing Roles ​

Settings › Roles lists the roles with their number of users on the left and the permissions of the selected role on the right. Every checkbox is saved immediately.

Predefined Roles ​

RoleForAllows
AdministratorTechnicians with full accessEverything. Anyone with “Manage users” and “Manage roles” always counts as administrator, even if single boxes are unchecked.
OperatorTechnicians without user and role managementView and edit hosts of all modules, tasks, updates, jobs, tunnels; scripts, groups, reports, policies, setup profiles, script variables, notifications, Tactical migration, QuickSupport, remote control and files.
SupportFirst-level phone supportRead, shell, task log, run saved scripts, remote control, QuickSupport, files (firewalls read-only).
ViewerRead onlyRead all modules and views, no sensitive permissions.

Permissions added by an update are granted to the predefined roles automatically where intended. Anything you uncheck on a system role stays unchecked.

Creating a Role ​

  1. Open Settings › Roles.
  2. Click +, enter name and color, Create.
  3. Check permissions on the General and Modules tabs.

Permissions ​

General tab ​

Permissions outside the host modules, sorted by area. Each row has the columns View and Manage (Use for QuickSupport). The checkbox in front of an area sets all permissions in it.

AreaContains
AdministrationUsers, roles, settings, customers, custom fields, onboarding
AutomationScripts, script variables, checks, playbooks, groups, policies and contracts, setup profiles
Monitoring and reportsNotifications, reports, Wazuh
Remote supportQuickSupport, Tactical migration
OtherTools

Since v3.63.0 these areas have their own permissions; before, only administrators could use them:

PermissionAllows
policies.manageCreate, change and delete policies and contracts. Assigning policies to customers and sites still needs Manage customers.
provisioning.manageMaintain setup profiles
scriptvars.manageView and maintain script variables, including setting secret values (values are never shown). Since v3.65.10, creating, changing and deleting also requires Manage scripts, because the values go straight into the script text.
notifications.manageNotification channels, alert and SMTP settings. A non-admin who changes the SMTP server, port, encryption or user has to enter the SMTP password again. A changed ntfy server needs a new token.
tactical.manageStart and control Tactical migrations. Access URL and API key stay with administrators. Setting contracts in the start dialog also requires Manage customers.
scripts.executeSince v3.72.0: run saved scripts on hosts (Scripts page, host context menu, bulk action, groups). Also needs a task right in the host's module (Tasks, Edit, Run updates or Reboot). Customer-bound users only reach hosts of their customer; if a foreign host is included, nothing starts. Before, only administrators could do this. Operator and Support have it by default.
scripts.manageCreate, change, delete scripts and restore older versions. Since v3.72.0 this works without admin rights, not for customer-bound users. System scripts (e.g. update scripts) can still only be changed by administrators.

These areas apply to all customers, so customer-bound users never get them, not even with the permission. Via MCP token they require admin scope.

Since v3.63.0, View settings (settings.view) shows Parameters, Run URLs, Branding and License read-only; secret values stay masked. Only administrators can change them there. MCP tokens and the audit log are visible to administrators only.

Since v3.63.0, Manage groups lets you create, change and delete groups (before: administrators only). Policies need Manage policies, virtual modules stay with administrators.

Modules tab ​

A table with permissions as rows and the modules (OPNsense, PVE, PBS, Linux, Windows, macOS) as columns. “–” means the permission does not exist in that module. The checkbox in a column header sets all permissions of a module, the All column sets one permission in all modules.

SectionPermissions
BasicsView, edit, delete, groups
TabsTask log, checks, jobs, agent
Updates and rebootView and run updates, schedules, reboot, package/Windows/macOS updates
ViewsHardware, disks, network, services, processes, event log, software, VMs, security …
Manage services and softwareStart, stop, install services, Docker, software
AccessShell, tunnels, RDP, RustDesk
Sensitive permissionsRemote control, files, kill processes, isolate host, diagnostics, config backups, firewall log, packet capture

Sensitive permissions are never granted through “all tabs”; check them one by one.

The search at the top right filters by name, description and key (e.g. files).

Multi-Factor Authentication (MFA) ​

Enabling MFA ​

  1. Click your username (bottom left in the sidebar).
  2. Open the Security tab and click Set up 2FA.
  3. Setup guides you through three steps: open the app, scan the QR code, enter the code. If you cannot scan, enter the displayed key manually (time-based/TOTP, 6 digits, 30 seconds). The key is hidden at first and can be copied.
  4. 2FA is activated automatically after the sixth digit. A wrong code is reported right below the input.

Mandatory 2FA ​

If an administrator requires 2FA for an account (2FA required in user management) and it is not set up yet, the page Set up two-factor sign-in appears after sign-in instead of the interface, with the same three steps. After the first valid code you continue straight away, without signing in again. Sign out ends the session.

Since v3.15.3 the server enforces the requirement, not only the interface: until setup is complete it answers only the own profile, 2FA setup and sign-out for this account. Data, tasks, shell, tunnels, the live connection and the account's MCP tokens are blocked. If an administrator sets the requirement while the user is signed in, their interface switches to the setup page on the next request. An active 2FA cannot be replaced by a new setup; deactivate it first (with password) or have an administrator reset it.

Signing in with 2FA ​

After username and password, the sign-in shows which user the code is requested for. The code is entered into six boxes (pasting and password managers work) and checked automatically after the sixth digit. A wrong code clears the field for the next attempt. Different user returns to the sign-in.

Supported Apps ​

  • Google Authenticator
  • Microsoft Authenticator
  • Authy
  • Any TOTP-compatible app

Resetting MFA ​

As an administrator, you can reset MFA for other users:

  1. Open the user in the management panel
  2. Click Reset MFA
  3. The user can set up MFA again on their next login

Security Recommendation

Enable MFA for all users with administrative privileges. This protects against unauthorized access even if passwords are compromised.

Access rules since v3.14.2 ​

  • Creating tasks (updates, reboot, scripts, agent update - via the UI, the API and bulk actions) requires a write right in the module: Tasks, Edit, Execute updates or Reboot. A pure View right is no longer enough. Customer-bound users only reach their own customer's hosts.
  • Free-form script content in a task is reserved for administrators and users with scripts.manage; everyone else runs saved scripts.
  • Reading tasks (/api/tasks) shows only modules with a view right and only the own customer's hosts; parameters such as keys or passwords are masked for non-administrators.
  • Live updates (host data, task output) reach customer-bound users only for their customer.
  • Aborting/resuming update runs requires Execute updates in the OPNsense module.
  • Customer-wide alert exclusions/mutes: see Notifications.

Access rules since v3.48.2 / v3.48.4 ​

A plain view right no longer allows changes. Before, some functions accepted any read right.

ActionRequired right
Create, change, clone, delete jobsJobs/schedules in the module (<module>.schedules); running also Execute updates
Create and edit hosts, assign groupsEdit in the module (groups also Groups)
Create, close, activate tunnelsTunnels in the module (<module>.tunnels)
Edit customers and sitescustomers.manage
Create, run, stop playbooksplaybooks.manage or scripts.manage
Wazuh exceptionswazuh.manage
Wake-on-LAN, cancel a task, install approved Windows updatessame as create task
Start OPNsense update runsExecute updates
PBS maintenance (GC, verify, prune, sync)Tasks in the PBS module

Customer-bound users see and edit jobs, tunnels, reports and playbook runs only for hosts of their customer. Jobs on groups or all hosts are hidden from them. The SSH password of an agent SSH tunnel is shown only with the Tunnels or Shell right.

Further changes:

  • Changing the password ends all other sign-ins of the account. An admin reset or deactivation ends all sign-ins.
  • MCP tokens stop working as soon as their creator still has to set up mandatory 2FA. A token with admin scope only works while its creator is an administrator. Tokens with read scope see no agent tokens and no onboarding token.
  • Tunnel client tokens check the user's current rights on every connection. A deleted token or a deactivated account disconnects immediately.
  • Web shell no longer reconnects by itself after a dropped connection; use Connect.

Deleting users and admin protection (from v3.48.6) ​

  • A user with audit log entries can no longer be deleted, only deactivated. The audit log keeps showing who did what.
  • Control refuses changes that would leave no active administrator: deactivating or deleting the last admin account, removing your own admin role, taking user and role management away from the Administrator role.
  • Permissions removed from system roles stay removed. Before, every restart added them again.
  • Control only creates the admin account on an empty installation, no longer after it was deleted.
  • Only administrators without a customer binding see the audit log.
  • Creating and editing sites needs customers.manage or Edit in a module.

Security from v3.48.8 ​

  • 2FA codes: after 5 wrong codes, two-factor sign-in of the account is locked for 15 minutes. A code works only once. The correct password no longer resets the failure counter.
  • Customer-bound users no longer reach hosts without a customer assignment.
  • Reports: templates, schedules, generating, preview and sending by e-mail need reports.manage. Reading and downloading stay as before; customer-bound users only see their customer's reports. The report data follows the user's module rights, the audit log only for administrators. PDF reports no longer load external files or addresses, only embedded images and the logo.

Security from v3.48.10 ​

  • Wazuh data (alerts, vulnerabilities, FIM, SCA) is shown only for modules the user can view; customer-bound users only see hosts of their customer.
  • Showing the RustDesk password needs the module's RustDesk right and is written to the audit log.
  • Config downloads from OPNsense (plaintext config.xml) are blocked for MCP tokens.
  • Web shell: after sign-out, deactivation or a password change an open shell accepts no more input.
  • Agent configuration (agent.json) is readable only by root or SYSTEM and administrators (installers from 3.48.10, existing hosts with the new agent).

Security from v3.48.15 ​

  • Editing checks: customer-bound users cannot create or change checks. Turning on Isolate host on critical result (or changing thresholds of an isolating check) needs the Isolate host right in the affected modules; scripts and remediation need scripts.manage.
  • Wazuh data follows the module rights for all non-administrators.
  • Stored reports are shown to users without a customer binding only with reports.view; reports with audit data only to administrators.
  • MCP tokens cannot transfer files, start agent calls or release an isolation.

DATAZONE Control Documentation