Permission model

There are four levels of permission: none, can_read, can_write, and can_manage.

none is the default state when there are no other permission grants.
- the object is not included in any list query response.
- direct queries of the object by uuid return 404 Not Found.
- Link objects require valid identifiers in head_uuid and tail_uuid, so an attempt to create a Link that references an unreadable object will return an error indicating the object is not found.
can_read grants read-only access to the record. Attempting to update or delete the record returns an error.
- can_read does not allow a reader to see any permission grants on the object except the object’s owner_uuid and the reader’s own permissions.
can_write permits changes to the record, including changing ownership and deleting the object.
- can_write cannot read, create, update or delete permission links associated with the object.
- can_write also implies can_read.
can_manage permits the user to read, create, update and delete permission links whose head_uuid is this object’s uuid.
- can_manage also implies can_write and can_read.

Ownership

All Arvados objects have an owner_uuid field. Valid uuid types for owner_uuid are “User” and “Group”. In the case of a Group, the group_class must be “project”.

The User or Group specified by owner_uuid has can_manage permission on the object. This permission is one way: an object that is owned does not get any special permissions on the User or Group that owns it.

To change the owner_uuid field, it is necessary to have can_write permission on both the current owner and the new owner.

Permission links

A permission link is a link object with:

owner_uuid of the system user.
link_class “permission”
name one of can_read, can_write, can_manage or can_login
head_uuid of some Arvados object
tail_uuid of a User or Group. For Group, the group_class must be a “role”.

This grants the permission in name for tail_uuid accessing head_uuid.

If a User has can_manage permission on some object, the user has the ability to read, create, update and delete permission links with head_uuid of the managed object. In other words, the user has the ability to modify the permission grants on the object.

The can_login name is only meaningful on a permission link with with tail_uuid a user UUID and head_uuid a Virtual Machine UUID. A permission link of this type gives the user UUID permission to log into the Virtual Machine UUID. The username for the VM is specified in the properties field. Group membership can be specified that way as well, optionally. See the VM login section on the ‘User management at the CLI’ page for an example.

Transitive permissions

Permissions can be obtained indirectly through nested ownership (can_manage) or by following multiple permission links.

If a User X owns project A, and project A owns project B, then User X can_manage project B.
If a User X can_read role A, and role A can_read Object B, then User X can_read Object B.
Permissions are narrowed to the least powerful permission on the path.
- If User X can_write role A, and role A can_read Object B, then User X can_read Object B.
- If User X can_read role A, and role A can_write Object B, then User X can_read Object B.

Projects and Roles

A “project” is a subtype of Group that is displayed as a “Project” in Workbench, and as a directory by arv-mount.

A project can own things (appear in owner_uuid)
A project can be owned by a user or another project.
The name of a project is unique only among projects and filters with the same owner_uuid.
Projects can be targets (head_uuid) of permission links, but not origins (tail_uuid). Putting a project in a tail_uuid field is an error.

A “filter” is a subtype of Group that is displayed as a “Project” in Workbench, and as a directory by arv-mount. See the groups API documentation for more information.

A filter group cannot own things (cannot appear in owner_uuid). Putting a filter group in an owner_uuid field is an error.
A filter group can be owned by a user or a project.
The name of a filter is unique only among projects and filters with the same owner_uuid.
Filters can be targets (head_uuid) of permission links, but not origins (tail_uuid). Putting a filter in a tail_uuid field is an error.

A “role” is a subtype of Group that is treated in Workbench as a group of users who have permissions in common (typically an organizational group).

A role cannot own things (cannot appear in owner_uuid). Putting a role in an owner_uuid field is an error.
All roles are owned by the system user.
The name of a role is unique across a single Arvados cluster.
Roles can be both targets (head_uuid) and origins (tail_uuid) of permission links.

Access through Roles

A “role” consists of a set of users or other roles that have that role, and a set of permissions (primarily read/write/manage access to projects) the role grants.

If there is a permission link stating that user A can_write role R, then we say A has role R. This means user A has up to can_write access to everything the role has access to.

Because permissions are one-way, the links A can_write R and B can_write R does not imply that user A and B will be able to see each other. For users in a role to see each other, read permission should be added going in the opposite direction: R can_read A and R can_read B.

If a user needs to be able to manipulate permissions of objects that are accessed through the role (for example, to share project P with a user outside the role), then role R must have can_manage permission on project P (R can_manage P) and the user must be granted can_manage permission on R (A can_manage R).

Special cases

Log table objects are additionally readable based on whether the User has can_read permission on object_uuid (User can access log history about objects it can read). To retain the integrity of the log, the log table denies all update or delete operations.

Permission links where tail_uuid is a User allow can_read on the link record by that user (User can discover her own permission grants.)

At least can_read on a Collection grants permission to read the blocks that make up the collection (API server returns signed blocks).

A user can only read a container record if the user has read permission to a container_request with that container_uuid.

can_read and can_write access on a user grants access to the user record, but not anything owned by the user.
can_manage access to a user grants can_manage access to the user, and everything owned by that user .
If a user A can_read role R, and role R can_manage user B, then user A can_read user B and everything owned by that user .

System user and group

A privileged user account exists for the use by internal Arvados components. This user manages system objects which should not be “owned” by any particular user. The system user uuid is {siteprefix}-tpzed-000000000000000.

Anoymous user and group

An Arvados site may be configured to allow users to browse resources without requiring a login. In this case, permissions for non-logged-in users are associated with the “anonymous” user. To make objects visible to anyone (both logged-in and non-logged-in users), they can be shared with the “anonymous” role. Note that objects shared with the “anonymous” user will only be visible to non-logged-in users!

The anonymous user uuid is {siteprefix}-tpzed-anonymouspublic. The anonymous group uuid is {siteprefix}-j7d0g-anonymouspublic.

Example

Previous: Singularity Next: Federation