Users, roles and scopes
Every person who signs in is a user. A user holds one or more roles, and a role is a set of permissions. A scope limits which clusters and nodes the user sees. The user has the union of the permissions of its roles, and the scope applies to every page and every API call.
Roles
Two roles are built in and kept up to date by the server at every start:
| Role | Permissions |
|---|---|
admin | Every permission, for every cluster and node. |
viewer | Read the inventory, agents, scans, reports, alerts and CPE mappings. |
Create more roles on the Settings page, in Roles, with a checklist of permissions. Give each role a description that says who it is for, for example Read-only access for the platform team.
The permissions are listed in the permissions reference. In short:
| Permission | Lets a user |
|---|---|
inventory.view | See findings, dependencies, assets and the dashboard. |
agents.view | See agents and agent releases. |
agents.manage | Register, change and remove agents, create tokens, roll out updates. |
scans.view | See scan runs, task runs and the scheduled tasks. |
scans.run | Start a scan. |
tasks.manage | Change the schedule of a task and run it now. |
reports.view | View and download reports and templates. |
reports.manage | Create, change and delete reports and templates. |
alerts.view | See alert channels, rules and events. |
alerts.manage | Change alert channels and rules. |
cpe.view | See the NVD dictionary status and the CPE mappings. |
cpe.manage | Import the NVD dictionary and change the mappings. |
settings.manage | Change the NVD, AI and automatic agent update settings. |
users.manage | Create, change and delete users, and assign roles and scopes. |
findings.triage | Record decisions on findings, and set their owner and ticket. |
roles.manage | Create and change roles. |
A user who holds users.manage or roles.manage can only grant what they hold
themselves, and cannot widen a scope beyond their own. Nobody can make themselves an
administrator this way.
Local users
On the Settings page, in Users, select Add user. Enter the e-mail address, a name, an initial password of at least eight characters, the roles, and the scope. The user can change the password on the Account page.
An administrator can change the roles and scope of any user at any time. An administrator cannot demote their own account; another administrator has to do that.
Scope
A scope is either every cluster and node, or a list of clusters and a list of nodes. A row is visible when its cluster is in the list, or its node is in the list.
- A node is the host name of the agent that reported the row. The node agent and the host agent of one Kubernetes node are one node.
- A host without a cluster is reached through its node only.
The scope applies to findings, dependencies, assets, agents, the dashboard, exports, reports and the MCP tools. Alert rules and channels, scan runs and settings are not scoped: they follow the permissions only. Registering an agent needs an unrestricted scope, because the scope cannot be checked before the agent reports.
Identity-provider accounts
An account from an identity provider is created on its first sign-in and matched by its
e-mail address. Its roles and scope come from the groups it belongs to, at every sign-in.
The mapping is a JSON list, given in OIDC_GROUP_MAPPINGS or SAML_GROUP_MAPPINGS:
[
{"group": "vop-admins", "roles": ["admin"], "all": true},
{"group": "vop-prod-viewers", "roles": ["viewer"], "clusters": ["prod"]},
{"group": "vop-node-watch", "roles": ["viewer"], "nodes": ["talos-worker-3"]}
]
A user in several groups gets the union of their roles and scopes. When mappings are configured, a user in no mapped group cannot sign in, and loses the roles it had. Without mappings, a new provider user gets the viewer role for every cluster and node, and existing users keep what they have. See Single sign-on for the setup.
The old settings OIDC_ADMIN_GROUPS and SAML_ADMIN_GROUPS still work and make the
members administrators. Use the mappings for new setups.