Security & Access Control

Fine-grained permission system that controls who can use which feature on which cluster.

It runs on top of the Proxmox VE permission model and is independent from it. Proxmox VE permissions decide what the application can do against the Proxmox VE API. The permissions of this page decide what each user can do inside the application.

Sections

The pages are under Admin Area → Security:

EE Users: create, edit and delete accounts, assign roles and permissions
EE Roles: named bundles of permissions, built-in or custom
EE App Tokens: credentials for programmatic access
EE Audit Logs: audit trail of logins and administrative actions
EE External Authentication: sign in with identity providers and domains, see External Authentication
Active Sessions: list of the connected browser sessions (sending messages and forcing a logout are EE)

Built-in accounts

Two accounts are created on first startup and cannot be deleted:

Account	Purpose
`admin@local`	Administrator. Created with the default password `Password123!`. See Getting Started.
`system`	Internal account used to run scheduled background jobs. It has no password and cannot log in.

While the default password of admin@local is in use, a persistent security warning with a Change password now link is shown after login.

UsersEE

The Users grid shows Photo, User Name, Display Name, Built In, Email confirmed, Is Active, 2FA, Lockout enabled, Lockout end and External logins (the providers linked to the account). 2FA marks the users who protect their login with two-factor authentication.

Toolbar actions:

Action	Description
Add / Delete	Create or delete a user. Built-in accounts and your own account cannot be deleted.
Export	Export the grid to Excel.
Reset password	Send the selected user a link to set a new password, after confirmation. The link is sent by email and is also shown, so it can be copied and delivered another way. It opens the same page as Forgot password? on the sign-in page and expires after one day. Not available for your own account: use the User Profile.
Disable 2FA	Turn off two-factor authentication for the selected user, after confirmation. Use it when a user has lost both the authenticator device and the recovery codes. The user signs in with the password only and is informed by email; the authenticator key and the recovery codes are discarded, so the next setup starts from a new QR code. Not available on your own account: use your profile. Requires the Disable 2FA permission.
Effective Permissions	Show every permission the selected user ends up with, and where each one comes from (granted directly or through a role). The dialog has a Flat and a Tree view. Shown only with the Read permission on users.

Click the User Name of a row to edit the user. A built-in account cannot be deactivated. The dialog has three tabs, five for an existing user: External logins and External sign-ins are described in External Authentication. The system account, used by the scheduled jobs, cannot be edited.

General

Field	Description
Photo	Click the picture to upload an image (any image the browser can read, up to 10 MB, scaled down to at most 128x128 pixels) or to clear it. Without a photo, the Gravatar of the email address is used.
Email	Email address. It is also the user name used to log in, and it must be unique.
Display Name	Name shown in the UI.
Is Active	When off, the user cannot log in. It is off by default for a new user: turn it on to let the user in.
Email Confirmed	Whether the email address has been confirmed. A user with an unconfirmed email cannot log in. Setting a password from a reset link also confirms the address. Read-only while creating a user.
Lockout Enabled	When on, the account is locked for a while after too many failed logins. Thresholds are set in appsettings.extra.json.

Permissions

Permissions granted directly to the user, in addition to the ones inherited from roles. See Permissions editor.

Roles of the user

Pick list with the available roles on the left and the Selected Roles on the right. Roles flagged as Default are always assigned and cannot be removed here.

How a new user gets access

A new user is created with a random password that nobody knows. The user receives an email with a link to confirm the email address. After confirming, the user sets a password with Forgot password? on the login page, which sends a reset link by email. The confirmation link is valid for one day: when it has expired, Resend email confirmation on the login page sends a new one, without an administrator.

Both emails are sent through the SMTP server configured in General Settings, so configure it before creating users. If email cannot be delivered, an administrator can turn on Email Confirmed in the user dialog and set the password with the CLI.

Locked out accounts: A locked account is unlocked automatically when Lockout end is reached. To unlock it immediately use the user unlock command of the CLI.

RolesEE

A role is a named bundle of permissions. The Roles grid shows Name, Description, Built In and Default. Click the Name to edit a role.

Field	Description
Name	Required. Cannot be changed after the role is created.
Description	Required.
Default	A default role is added automatically to a user when the user is created or edited, and cannot be removed from the user’s role list. App tokens do not receive it automatically: it can be picked for a token like any other role.
Permissions	The permissions granted by the role. See Permissions editor.

The application creates the built-in roles: the administrator role, the cluster roles and one or more roles per module. They cannot be deleted and are read-only: name, description, default flag and permissions cannot be changed. To customise access, create a new role.

Permissions editor

The same editor is used for users, roles and app tokens. Each entry grants one permission and is made of:

Column	Meaning
Cluster	The cluster the permission applies to, or All clusters.
Permission	The operation that is allowed. Permissions are grouped by module. The Key column (hidden by default) shows the technical key.
Path	The resource path the permission applies to.
Propagated	When on, the permission also applies to the paths below Path.
Built In	Entries created by the application. They cannot be edited or removed.

The editor has three tabs that show the same entries in different ways:

Tab	Use it to
List	Flat grid with Add, Delete and in-row editing of cluster, permission, path and propagation.
By Permission	Tree of all permissions with one column per cluster. Tick a checkbox to grant a permission on a cluster, or tick a group to grant all the permissions below it. Only set hides the branches with no granted permission.
By Path	One row per path and one column per cluster. Each granted permission is a badge: click it to remove it, use the + button to add one.

App TokensEE

App tokens are credentials for programmatic access, used instead of a user name and password. The AI Server (MCP) authenticates its clients with an app token.

The App Tokens grid shows Name, Owner, Is Active, Created At and Expires At. Inactive and expired tokens are highlighted.

Field	Description
Name	Required. Identifier for the token.
Owner	Optional user the token is linked to. Empty means a system token.
Expires At	Optional date and time after which the token is rejected. Empty means it never expires.
Is Active	When off, the token is rejected. Default: on.
Permissions / Roles	Grant single permissions, assign roles, or both. Unlike users, a token does not receive the Default roles automatically: pick them in the list when the token needs them.

When you create a token the secret is shown once in a dialog: copy it immediately, it will not be shown again.

Toolbar actions:

Action	Description
Regenerate	After confirmation, generates a new secret for the selected token and shows it once. The previous secret stops working immediately. Requires the Edit permission on app tokens.
Effective Permissions	Shows every permission the token ends up with, directly or through roles. Shown only with the Read permission on app tokens.
Export	Export the grid to Excel.

Active Sessions

The Active Sessions page lists the browser sessions currently connected to the application. Columns: UserName, Login, Ip Address, Device, Platform, Browser, Current Page and Last Activity. Platform Version, Browser Version and User Agent are hidden by default and can be added from the column picker.

Action	Description
EE Send Message	Sends a notification to the selected sessions. Fields: Title, Message (required) and Severity (`Info`, `Success`, `Warning`, `Error`).
EE Force logout	After confirmation, terminates the selected sessions. The user sees the message “Your session has been terminated by an administrator”.

Each user sees their own sessions in the User Profile.

Audit LogsEE

The Audit Logs grid records logins (successful and failed) and administrative actions such as user, role and maintenance operations. Sign-ins through a domain or an identity provider are recorded as Login-Domain and Login-External, see External Authentication.

Columns: Timestamp, User Name, Success (Success or Failed), Action, IP Address and User Agent. Expand a row to read the Details of the entry, with a button to copy them.

Every column can be filtered and sorted, and the grid can be grouped by column.
Export saves the grid to Excel.
Delete removes the selected entries. It has a permission of its own, Delete audit logs.
Old entries are removed with Maintenance → Cleanup Audit Logs. There is no automatic cleanup.
Audit logs are stored in the system schema of the cv4pve-admin database, separately from Proxmox VE.

Each user can read their own entries in the User Profile.