Skip to main content
PathMon

Chapter 24 of 26

Users, Roles, and RBAC

Updated Read the full guide

PatchMon uses role-based access control (RBAC) to decide who can see and do what inside the application. Every user has exactly one role, and every role is a collection of permissions. This page covers the built-in roles, the full permission list, and how to manage users and roles from the Settings UI.

Related pages:

  • Setting Up OIDC / Single Sign-On: authenticate users against an external IdP
  • Setting Up Microsoft Azure Entra ID (SSO) with PatchMon: Entra-specific walkthrough
  • Two-Factor Authentication: per-user TOTP and trusted devices

The Built-In Roles

PatchMon ships with five roles. You see these in Settings → Users (in the Role dropdown) and in Settings → Roles (as the matrix columns).

Role Default Permissions Typical Use
Super Admin (superadmin) Everything, including managing other superadmins The very first user, or dedicated platform owners
Admin (admin) Everything except managing other superadmins Day-to-day platform administrators
Host Manager (host_manager) Monitoring + host/infrastructure management + operations (patching, compliance, alerts, automation, remote access) NOC / Ops engineers
User (user) Monitoring + data export Engineers who need to look but not break
Readonly (readonly) Monitoring only Auditors, read-only dashboards, management

Two important rules about built-ins:

  • Cannot be deleted. superadmin, admin, host_manager, user and readonly are always present. The Delete button does not appear for them.
  • The core three cannot have their permissions edited. superadmin, admin and user are locked: their permission matrix is hardcoded and the Edit button is disabled. host_manager and readonly can still be edited if you want to tune them.

First user is always Super Admin. When PatchMon is first installed and has no users, the setup wizard creates the initial account as superadmin, regardless of what role you type. If OIDC is configured for auto-create before first boot, the very first OIDC login is also promoted to superadmin automatically so you cannot lock yourself out.

The Full Permission List

Permissions are grouped into four risk tiers. The colour you see in the Roles matrix corresponds to this risk level.

Monitoring & Visibility (Low risk)

Read-only access to dashboards, hosts, packages, reports, and logs.

Permission key Label What it lets the user do
can_view_dashboard View Dashboard View the main dashboard and its stat panels
can_view_hosts View Hosts See the host list, host detail pages, and connection status
can_view_packages View Packages See the package inventory across all hosts
can_view_reports View Reports See compliance scan results and alert reports
can_view_notification_logs View Notification Logs See notification delivery history and status

Host & Infrastructure (Medium risk)

Create, modify and delete hosts, packages, and containers.

Permission key Label What it lets the user do
can_manage_hosts Manage Hosts Create / edit / delete hosts, host groups, repositories and integrations
can_manage_packages Manage Packages Edit package inventory and metadata
can_manage_docker Manage Docker Delete Docker containers, images, volumes and networks

Operations (Medium-High risk)

Day-to-day NOC tasks.

Permission key Label What it lets the user do
can_manage_patching Manage Patching Trigger patches, approve patch runs, manage policies
can_manage_compliance Manage Compliance Trigger compliance scans, remediate findings, install scanners
can_manage_alerts Manage Alerts Assign, delete and bulk-action alerts
can_manage_automation Manage Automation Trigger and manage automation jobs
can_use_remote_access Remote Access Open SSH and RDP terminals against managed hosts

Administration (High risk)

Organisation-wide control.

Permission key Label What it lets the user do
can_view_users View Users See the user list and account details
can_manage_users Manage Users Create, edit and delete user accounts
can_manage_superusers Manage Superusers Manage superadmin accounts and elevated privileges, and turn OIDC / SSO on or off or change its provider, client credentials, redirect URI, local login, the password fallback during an SSO outage, user auto-creation, email trust, role sync and role mapping
can_manage_settings Manage Settings System configuration, OIDC / SSO (the provider and role mapping also need can_manage_superusers), AI, alert config, enrollment tokens
can_manage_notifications Manage Notifications Configure notification destinations and routing rules
can_export_data Export Data Download and export data and reports

Billing: On PatchMon Cloud there is also a can_manage_billing permission that governs access to the Billing page. On self-hosted instances this permission exists in the schema but the Billing page is not enabled by default.

Viewing the Role Matrix

  1. Sign in as a user with can_manage_settings.
  2. Go to Settings → Roles.
  3. You'll see a matrix: rows are permissions (grouped by tier), columns are roles. A green tick means the role has that permission.

Each column header also shows an n/N counter showing the number of permissions that role currently holds out of the total 20.

Creating a Custom Role

Custom roles let you tailor the permission set beyond the built-in five.

Availability: The Add Role button is only shown when the rbac_custom module is enabled on your PatchMon deployment. On self-hosted installs this module is typically enabled by default; on PatchMon Cloud it depends on your plan. If you don't see Add Role and the URL https://patchmon.example.com/settings/roles shows a "Not Available" screen, the module isn't enabled on your plan.

To create one:

  1. Go to Settings → Roles.
  2. Click Add Role in the top-right.
  3. Fill in the modal:
    • Role Name: lowercase, underscores instead of spaces. Examples: host_manager, compliance_auditor, noc_operator. This is the internal key; it cannot be renamed later.
    • Preset (optional): four quick-start presets are available:
      • Read Only: just the Monitoring & Visibility group
      • Operator: everything except the Administration group
      • Admin: every permission. Only a superadmin can use this preset; for anyone else the role is refused because it includes can_manage_superusers.
      • Clear All: start from zero
    • Permissions: tick / untick individual permissions, or use the Select all / Deselect all shortcut on each group header.
  4. Watch the counter at the bottom (n/20 permissions selected) as a sanity check.
  5. Click Create Role.

You can only grant permissions you hold. Unless you are a superadmin, a role you create or edit may only contain permissions your own role has. Saving a role with any other permission is refused with a message naming the permissions you lack. For example, an admin cannot create a role with can_manage_superusers, so the Admin preset only works for a superadmin.

The new role appears as a new column in the matrix and is selectable when creating or editing users.

Editing a Custom Role

  1. In the matrix, click the pencil icon in the column header of the role you want to edit.
  2. An editor panel opens below the matrix with all permissions listed.
  3. Tick / untick as needed, then click Save.

Changes take effect immediately. Any session held by a user with that role has its in-memory permissions refreshed on their next request.

You cannot edit or delete a role that holds a permission your own role lacks.

Deleting a Custom Role

You can only delete a role that is not assigned to any user. If any user holds that role, the delete endpoint rejects the request with "Cannot delete role: users are assigned to it". Reassign those users to a different role first (see Editing a Role for an Existing User).

To delete:

  1. Click the pencil in the role's column header to open the editor panel.
  2. Click Delete (appears only for non-built-in roles).
  3. Confirm.

Creating Users

Go to Settings → Users and click Add User in the top-right.

Field Notes
Username Minimum 3 characters. Lowercase recommended
Email Must be a valid email. Used for OIDC account linking and email alerts
First Name / Last Name Optional
Password Must satisfy the active password policy (configured under Settings → Server Config → Security)
Role Choose from built-in or custom roles

Click Add User. The account is created immediately and can sign in straight away.

Role escalation protection: Only a superadmin can make someone an admin. Other than that, you can only give a user a role whose permissions are all held by your own role. A non-superadmin can create and manage superadmin accounts only if their role holds every permission, including can_manage_superusers.

Self-Service Sign-Up

PatchMon can also let users register themselves rather than having an admin invite them.

  1. Go to Settings → Users.
  2. Scroll to User Registration Settings.
  3. Tick Enable User Self-Registration.
  4. Pick a Default Role for New Users: the role that self-registered accounts are assigned. The same rule as assigning a role applies: only a superadmin can choose admin or superadmin, and anyone else can only choose a role whose permissions are all held by their own role. A save that breaks this rule is refused.
  5. Click Save Settings.

A sign-up link now appears on the login page. Anyone who can reach the login page can create an account.

Security warning: Only enable self-registration on internal or private-network deployments. If your PatchMon is internet-facing, leave it off and invite users manually, or front it with OIDC SSO (which lets your IdP decide who can log in).

Editing a Role for an Existing User

  1. Go to Settings → Users.
  2. Find the user in the table and click the Edit (pencil) icon.
  3. Change Role in the dropdown and click Save.

Important side effects:

  • Sessions are revoked. When a user's role changes, all of their existing JWT sessions are invalidated on the server. They must sign in again. This ensures the old role's privileges cannot be replayed from an existing browser tab.
  • You cannot change your own role. The API rejects a self-role change with "Cannot change your own role".
  • You can only change the role of a user whose current role is strictly below yours. An admin cannot change another admin's role, so one admin cannot demote another and then take over the account. Only a superadmin can change an admin's role. A superadmin can change anyone's role except their own.
  • You cannot promote a user above yourself. You can only assign a role whose permissions are all held by your own role, so an admin cannot promote a user to superadmin. Only a superadmin can assign the admin role.

Resetting a User's Password

  1. In the users table, click the Reset (key) icon on that user's row.
  2. Enter a new password.
  3. Click Reset Password.

After a reset, all of that user's sessions and trusted-device records are revoked. This is the standard post-compromise response. The user must sign in with the new password on every device.

You cannot reset the password of an inactive user. Reactivate them first.

Unlinking a User's SSO Identity

When a user signs in with OIDC / SSO, PatchMon binds their account to that identity at that provider. If the identity changes, for example because the user was deleted and re-created at the provider, or you moved to a different provider (including a different realm or application on the same server), their SSO login is refused with "Unable to sign in with this account". After a provider migration, unlink each existing SSO user so they can sign in through the new provider.

  1. Click the Edit (pencil) icon on the user's row.
  2. Under SSO identity, click Unlink SSO identity and confirm.

Their next SSO login links the account to the new identity, keeping their role and settings, provided the identity provider sends a verified email address that matches the account. The section only appears for accounts that are linked.

  • You can only unlink users whose role is strictly below yours (your role holds every permission theirs grants, and at least one more), and never your own account. A superadmin can unlink anyone except themselves. This is stricter than editing, because unlinking and then changing the email address would hand an SSO-only account to someone else.
  • Every unlink, and every refused attempt, is written to the audit_logs table (event user_oidc_unlink).
  • If Trust unverified email is on in Settings > OIDC / SSO, the verified-email check is skipped, so whoever next signs in with that address claims the account. Ask the user to sign in straight after you unlink. While the setting is on, superadmins cannot be unlinked.

Disabling (Deactivating) a User

Disabling is the safer alternative to deletion. The user record, their history, and their audit trail are preserved, but they cannot log in.

  1. Go to Settings → Users.
  2. Click the Edit icon on the user you want to disable.
  3. Untick the Active checkbox.
  4. Click Save.

Effects:

  • All their sessions are revoked immediately.
  • All their trusted devices are revoked (so re-activating them later cannot reuse a "remember this device" cookie that predates the deactivation window).
  • The user's row is shown with a red Inactive badge in the users table.
  • A sign-in attempt with a wrong password gets the usual Invalid credentials message. Only someone who enters the account's correct password is told Account is disabled, so the message cannot be used to find out which accounts exist.

To re-enable: edit and tick Active again.

Deleting a User

Deletion is permanent and removes the user record and their associated dashboard preferences, sessions, trusted devices and notification preferences.

  1. Click the Delete (trash) icon on the user's row.
  2. Confirm.

Restrictions:

  • You cannot delete your own account.
  • You cannot delete the last superadmin (the API refuses).
  • You cannot delete the last admin if there are no superadmin users (ensures at least one admin always exists).
  • You cannot delete a user whose role holds a permission yours lacks.

How Permissions Are Evaluated

  • Every role, including Admin and Super Admin, has its permissions read from the role_permissions table on each request; there is no built-in bypass. By default superadmin holds every permission and admin holds every permission except can_manage_superusers. Their rows cannot be edited from the UI, so a change to them can only come from direct database access.
  • Changes made in Settings → Roles take effect on the user's next API call; no restart required.
  • Role hierarchy for user management is based on permissions, not on role names. One role is at or below yours when every permission it grants is also granted to your role. A superadmin is above every other role.

You can only assign, modify, delete, or reset the password of users whose role is at or below yours, and you can only create, edit or delete roles that are at or below yours. Changing a user's role and unlinking an SSO identity need a role strictly above the target's current role (see Unlinking a User's SSO Identity). Custom roles are compared by their permissions, not their names, so a custom role that holds all of an admin's permissions plus at least one more outranks admin and can change an admin's role, reset their 2FA or unlink their SSO identity. This is enforced separately from the permission checks. A custom role granted can_manage_users therefore cannot touch an account whose role has, for example, can_manage_settings unless it holds can_manage_settings too.

When OIDC Role Sync Is Enabled

If Settings → OIDC / SSO → Sync roles from IdP is on, PatchMon stops letting admins manage users and roles from the UI. Instead:

  • The Add User and Add Role buttons disappear.
  • The Users tab shows a read-only list.
  • The Roles tab shows a banner reminding you that group membership in your IdP drives role assignment via environment variables: OIDC_SUPERADMIN_GROUP, OIDC_ADMIN_GROUP, OIDC_HOST_MANAGER_GROUP, OIDC_USER_GROUP, OIDC_READONLY_GROUP.
  • Users' roles are re-evaluated on every login based on their current IdP group membership.

If you want to use OIDC for authentication but still manage roles locally in PatchMon, leave Sync roles from IdP off. See Setting Up OIDC / Single Sign-On for the full toggle reference.

Troubleshooting

"You do not have permission to assign the role: admin"

Only a superadmin can create or promote users to admin or superadmin. If you're an admin and try to promote someone to admin, the API refuses. Ask a superadmin to do it.

"Cannot modify built-in role permissions"

The superadmin, admin and user rows are locked against permission edits. If you need a role with tweaked permissions, create a custom role based on a preset and assign users to that instead.

"Cannot delete role: users are assigned to it"

Before a role can be deleted, reassign every user who holds it. Use Settings → Users → Edit to change each user's role, then try the delete again.

"Cannot delete the last superadmin user" / "Cannot delete the last admin user"

At least one superadmin must always exist. If there are no superadmins at all, at least one admin must exist. Create a replacement first (and sign in as them to confirm the login works) before deleting the final one.

User's old role is still in effect after I changed it

Changing a role revokes all existing sessions, but the user's browser may still hold an old JWT cookie that hasn't been rejected yet. Ask them to refresh the page or sign out and back in; the server will reject the stale token and redirect them to login.

"Add User" / "Add Role" button is missing

Three possible causes:

  1. Your role doesn't have can_manage_settings or can_view_users. Check /settings/users: if the page is empty or you get a Forbidden, your role lacks the view permission.
  2. OIDC role sync is on. See When OIDC Role Sync Is Enabled.
  3. The rbac_custom module is not enabled. This only affects the Add Role button on the Roles tab. Custom role creation is a gated feature. The Add User button on the Users tab is always available when the other two conditions are met.