ACL v2: Fine-grained access control in Xen Orchestra
With the v2 of the ACL system, Xen Orchestra takes a new step forward in permission management. Where v1 offered basic per-object access control, v2 introduces a full RBAC (Role-Based Access Control) model, with effects, selectors, and an action hierarchy.
What changes
The old approach allowed granting access to an object (a VM, an SR…). Simple, but limited: there was no way to say "this user can shutdown only VM with tag: foo".
Another major limitation of v1: it only covered XAPI objects — VMs, hosts, SRs, networks, so user, groups, backups, schedules, jobs,... was out of scope.
ACL v2: REST API exclusive
ACL v2 is available through the REST API only. The JSON-RPC API (used by XO5) stays on ACL v1, and conversely: ACL v1 is not available on the REST API.
Key concepts
Roles and privileges
A role is a named set of privileges. Each privilege defines:
- a resource type (
vm,sr,network,backup-job…) - an action (
read,start,shutdown:clean,delete…) - an effect:
allowordeny - an optional selector to target specific objects (complex-matcher format)
Actions are hierarchical. Granting shutdown covers both shutdown:clean and shutdown:hard. But granting shutdown:clean does not cover shutdown as a whole. deny always takes precedence over allow.
Built-in roles
Actually, 4 template roles are provided out of the box:
- Read only — full read-only access to the infrastructure
- VMs read only — read-only access to VMs only
- VMs power state manager — manage VM power state (start, stop, reboot, pause…)
- VMs creator — create VMs from templates
These roles are immutable and automatically updated on startup — they cannot be assigned directly. To use them, copy the template into a new role and assign that copy to your users or groups. This ensures the built-in templates always stay up to date without affecting your custom configurations.
Selectors: object-level precision
A selector restricts a privilege to objects matching certain properties. For example:tags:qa
This allows add a privilege only on VMs tagged qa.
What makes this mechanism powerful is its dynamic nature. Selectors are evaluated in real time.
In case the users subscribed to VMs changes, if the qa tag is added to an existing VM, and the user have a read privilege, he will see that VM appear as a new object — the user will receive an add event, not an update. Conversely, if the tag is removed, he will receive a remove event: the VM disappears from his scope.
Events are always from the user's perspective, not XOA's. For XOA, it is a simple tag update. For the ACL user, it is an object entering or leaving their scope.
This enables very practical use cases: a single tag is enough to grant or revoke access to a resource, without touching roles or privileges at all.
Assigning Roles to Users and Groups
A role can be attached to a user or a group. A user's effective roles are the union of their direct roles and those of their groups.
REST API integration
All endpoints are exposed through the REST API:
GET/POST /acl-roles— list and create rolesPUT/DELETE /acl-roles/{id}/users/{userId}— attach/detach a role to a userPUT/DELETE /acl-roles/{id}/groups/{groupId}— attach/detach a role to a groupGET/POST /acl-privileges— list and create role's privilegesPOST /acl-roles/{id}/actions/copy— copy a role
Each REST API endpoint declares the required privileges to access it via the swagger UI. If an endpoint declares none, it is admin-only.
A concrete example
Alice is a member of the QA team. She needs to be able to start and stop VMs in her test environment, but must not touch anything in production.
With ACL v2:
- Create a
QA Operatorrole with following privileges:{resource: 'vm', action: 'read', effect: 'allow', selector: 'tags:qa'}{resource: 'vm', action: 'start', effect: 'allow', selector: 'tags:qa'}{resource: 'vm', action: 'stop', effect: 'allow', selector: 'tags:qa'}
- Attach this role to Alice (or her group)
That's it. Alice cannot touch production VMs, and any attempt is blocked with an explicit error.
Another concrete example
Bob is allowed to rename VMs, but only while they are running — to prevent renaming VMs that are off and might be part of an automated process.
With ACL v2:
- Create a
Running VM Renamerrole with following privilege:{resource: 'vm', action: 'read', effect: 'allow', selector: 'power_state:Running'{resource: 'vm', action: 'update:name_label', effect: 'allow', selector: 'power_state:Running'
- Attach this role to Bob
Bob can rename and see any running VM.
One last example
Carol can see all VMs in the infrastructure, except those tagged
prod.
With ACL v2:
- Create a
Non-Prod VM Readerrole with two privileges:{resource: 'vm', action: 'read', effect: 'allow'}no selector, grants read access to all VMs{resource: 'vm', action: 'read', effect: 'deny', selector: 'tags:prod'explicitly denies access to production VMs
- Attach this role to Carol
Since deny always takes precedence over allow, Carol can browse the full VM list — except production VMs, which are completely invisible to her.
ETA on master: early April
Already testable on mra-acl-v2 branch, but not yet finished
List of possible actions (by resource)
{
update: {
name_label:true,
name_description:true,
...
}
}
is translated into -> update:name_label, update:name_description, ...
Please note that ACL v2 is currently only accessible via the REST API. Support in the XO6 user interface will be available later.
