vStack Center access model

Problem and purpose

A single cluster serves many users: the platform administrator, the administrator of an individual VDC (virtual data center), a user who works only with their own machines, and a viewer who needs only read access and reports. They all use the same cluster HTTPS endpoint and call the same methods. A single "admin / non-admin" flag cannot distinguish them: "view a network" and "edit your own network" are different permissions, and the latter also applies to a limited set of objects.

This calls for a model with three layers rather than a single list of roles. A role consists of privileges, a privilege lists the methods it grants access to, and a scope attribute limits the privilege to specific objects. Without a clear understanding of these three layers, the platform's behavior can seem inconsistent: a user with an administrator role in one VDC is denied access in another, and a method available to "all authorized users" returns different sets of fields for different roles.

This page explains the model. For account creation and maintenance, see How to manage users; for building and assigning a custom role, see How to configure roles and privileges; for sessions and sign-in policy, see How to configure sign-in and manage sessions.

Model and entities

Access in vStack Center is built from four entities.

User. A cluster account with a numeric id, a name, a full name fullname, and created and modified timestamps. An account has no password when it is created; the password is set in a separate call. Sign-in counters are stored alongside the profile: failed_login_attempts, first_failed_at, and locked_until. Identifiers id < 10 are reserved for built-in accounts: the platform prohibits deleting them or changing their role assignments.

Privilege. A unit of permission. A privilege has an id, a human-readable name, a category category_id, a set of scope_ids, and its main field, methods: a list of JSON-RPC method names that the privilege grants access to. The privilege, rather than the role number, determines who can call a method.

Scope attribute. An attribute that limits a permission to a subset of objects. It has an id, a name, and a self_referencing flag. There are two types of attributes, with a fundamental difference between them:

Attribute	self_referencing	Value source	What it limits
vdc_id	false	the user_role_scope assignment table	the list of VDCs in which the role applies
creator	true	generated from the caller's user_id	objects created by the caller

Role. A named set of privileges plus a set of scope attributes. Roles are classified as fixed or custom based on their identifier range.

ID	Role name	Type	Level
1	Cluster Master	fixed	cluster
2	vDC Admin	fixed	VDC
3	vDC User	fixed	VDC
4	vDC Viewer	fixed	VDC
5	Resource Viewer	fixed	cluster
6	Security Admin	fixed	cluster
7	VM Developer	fixed	VDC
≥ 10000	custom name, up to 64 characters	custom	determined by scope attributes

The Security Admin and VM Developer roles were introduced in 3.0.3. The first operates at the cluster level and grants access to the security log and auditing; the second operates within a VDC and is designed for creating and configuring virtual machines.

Fixed roles have an empty (null) creator field and cannot be modified or deleted. For a custom role, creator stores the id of the user who created it. The Cluster master role has no scope binding: its scope_ids is an empty array, so it applies to the entire cluster.

The fifth entity is a relationship rather than an object: an assignment. A role is assigned to a user together with a scope attribute value, within a specific VDC, rather than without a scope. A single user can hold the vDC admin role in one VDC and vDC viewer in another.

How access checks work

Each request passes through four checks in sequence.

1. Session. The cluster validates the session token and replaces it with a numeric user identifier; from then on, the user is identified within the cluster by this identifier. A request without a token is rejected with code -9494 ("No session token") before any method logic runs.
2. Caller roles. The identifier is used to build an assignment map: which roles the user has in which VDCs. Users can view their own map; each assignment includes the VDC, role, role name, and a GI account flag.
3. Privilege. The method is checked against the methods lists of the privileges granted by the user's roles. If the privilege is missing, access is denied. The role number is irrelevant here: a role matters only as a set of privileges.
4. Scope. If a privilege has scope_ids, the permission applies only to objects within that scope. Values for vdc_id come from role assignments; values for creator come from the caller's uid. An empty scope_ids means a global privilege.

The difference between a global and a scoped permission is visible in the assignment itself: each role and scope attribute pair either lists attribute values or has an "unrestricted" flag. This flag means that the assignments contain no values and the role is not restricted by this attribute. For example, the vDC admin role may have its vdc_id attribute restricted to two VDCs, while the Resource viewer role has no scope attributes at all.

Privileges are grouped into categories. A category only groups privileges; it does not affect permission checks. The category set is seeded in the cluster database and grows as the platform adds domains. The first ten are vDC, VM, Network, Edge, Storage, Node, Cluster, User, Misc, and Auth; Security, User Interface, Unified Storage, OS Image Library, and Backup have been added to them.

note

The API documentation example lists only the first ten categories, while the database contains fifteen. The discrepancy is in the example, not the platform's behavior: the complete category reference is returned, so use the actual set of categories in your cluster.

Two examples from the privilege registry show both types of restrictions:

Privilege	Category	Scope	Grants access to method
1000 View vDC	1 (vDC)	[1] — vdc_id	vdc-list
2010 Edit Own Network	3 (Network)	[2] — creator	net-set

The first applies in the VDCs where the role is assigned. The second applies only to networks created by the caller, regardless of the VDC.

Model boundaries

The privilege model does not cover user management itself. Many methods in the user-* group require a global role and return code -403 with the message "Access denied" to everyone else. This applies to user-list, user-get, user-create, user-delete, user-unlock, user-role-assign, user-role-deassign, user-roles-map, and the user-remote-* and user-vhost-* restriction methods. Cluster administrator permissions cannot be granted partially; this is a deliberately closed set of permissions.

The same principle imposes four restrictions that prevent creating a custom role that is "almost Cluster master":

Restriction	Reason	What to do instead
Role management privileges 7111–7113 cannot be assigned to a custom role	Otherwise, the role could extend its own permissions	Leave role management to Cluster master
A self-referencing attribute (creator) is prohibited in a custom role's scope_ids	Its value is generated from user_id, so there is no value to bind to the role	Use vdc_id, and use existing Own privileges for the "own objects only" restriction
Fixed roles (id < 10000) cannot be modified or deleted	They define the platform's core contracts	Create a custom role with the required set of privileges
Accounts with id < 10 cannot have their role assignments changed or be deleted	Built-in accounts keep the cluster operational	Create a separate user

Another behavior that may be surprising at first: the same operation can return different amounts of data for different roles. Any authorized user can read the cluster's security settings, but while everyone can see password requirements, only Cluster master can see the failed attempt limit and lockout duration.

Where to find this in the interface

Accounts and roles are in the same section. Path: Provider Data Center → Users & Roles. The section has two tabs: Users, an account table with the Name, Status, Full Name, Created, and Changed columns; and Roles, a role table with the Name, scope, Creator, Created, and Modified columns. The scope column in the role table is the role's set of scope attributes.

A role opens on a separate screen (the address bar shows #/panel/allusers/roles/). Privileges are grouped into sections there: vDC, VM, Network, Edge, Storage, Node, Cluster, User, Misc, Auth, Security, and User Interface. On a fixed role's screen, the Actions, Reset, and Save changes buttons are disabled, reflecting the prohibition on modifying fixed roles.

See also

• Account creation, passwords, unlocking, and network restrictions — How to manage users.
• Building a custom role and assigning a role in a VDC — How to configure roles and privileges.
• Sessions, password policy, and account lockout — How to configure sign-in and manage sessions.
• Exact field sets and the complete list of error codes — Fields and error codes for access methods.

API methods

API operations covered on this page: privilege-categories, privilege-list, privilege-scopes, role-list, role-get, role-privilege-list, user-role, user-roles, user-roles-v2, user-roles-map, auth-security-settings-get — see the API reference.