---
layout: default
-navsection: api
+navsection: architecture
navmenu: Concepts
title: "Permission model"
-
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+There are four levels of permission: *none*, *can_read*, *can_write*, and *can_manage*.
-Each API transaction (read, write, create, etc.) is done on behalf of a person.
-
-* An end user, via a web app
-* The owner of an installed app
-
-A user (person) is permitted to act on an object if there is a path (series of permission Links) from the acting user to the object in which
-
-* Every intervening object is a Group or a User, and
-* Every intervening permission Link allows the current action
-
-Each object has exactly one _owner_, which can be either a User or a Group.
-
-* If the owner of X is A, then A is permitted to do any action on X.
+* *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*.
-h3. Tokens
+h2. Ownership
-An authorization token is issued at a user's request, and supplied to an API client using some suitable mechanism (_e.g._, cookie or application config file for a web app; environment variable or .rc-file for a CLI app).
+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".
-A user can have multiple valid tokens at a given time. At the user's option, a token can be restricted to a combination of
+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.
-* API client program
-* time interval
-* transaction type
+To change the @owner_uuid@ field, it is necessary to have @can_write@ permission on both the current owner and the new owner.
-h3. System pseudo-user
+h2(#links). Permission links
-A privileged user account exists for the use of built-in Arvados system components. This user manages system-wide shared objects which can't really be "owned" by any particular user, like
+A permission link is a link object with:
-* Jobs and job steps (because a given job can be "wanted" by multiple users)
-* Provenance metadata (because no user should be able to modify this directly)
-* Storage metadata like
-** redundancy verified as N× at time Y
-** contents of collections A and B are identical
+* @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".
-The system pseudo-user's uuid is @{siteprefix}-tpzed-000000000000000@.
+This grants the permission in @name@ for @tail_uuid@ accessing @head_uuid@.
-h2. Example scenarios
+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.
-h3. 1. Private objects
+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":{{ site.baseurl }}/admin/user-management-cli.html#vm-login for an example.
-Alfred stores 3 data Collections in Keep and adds them to a new Group.
+h3. Transitive permissions
-The Collections and the Group can only be seen by Alfred, administrators, and the system user.
+Permissions can be obtained indirectly through nested ownership (*can_manage*) or by following multiple permission links.
-The data in the Collections can only be retrieved by Alfred, administrators, and the system user.
+* 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.
-h3. 2. Public objects
+h2. Projects and Roles
-George creates a "PGP public data" Group, and grants "read" permission to all users.
+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.
-* ...by adding a Link: "All users" Group _can_read_→ "PGP public data" Group
+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":{{ site.baseurl }}/api/methods/groups.html 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.
-George stores 4 data Collections in Keep and adds them to the "PGP public data" Group
+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.
+* By default, all roles are visible to all active users. However, if the configuration entry @Users.RoleGroupsVisibleToAll@ is @false@, visibility is determined by normal permission rules, _i.e._, a role is only visible to users who have that role, and to admins.
-* ...by adding a Link: Group _can_read_→ Collection
+h3. Access through Roles
-Anyone who can connect to Arvados can log in with a Google/OpenID account and read the data.
+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.
-h3. 3. Group-managed objects
+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.
-Three lab members are working together on a project. All Specimens, Links, Jobs, etc. can be modified by any of the three lab members. _Other_ lab members, who are not working on this project, can view but not modify these objects.
+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.
-h3. 4. Group-level administrator
+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).
-The Ashton Lab administrator, Alison, manages user accounts within her lab. She can enable and disable accounts, and exercise any permission that her lab members have.
+h2. Special cases
-George has read-only access to the same set of accounts. This lets him see things like user activity and resource usage reports, without worrying about accidentally messing up anyone's data.
+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.
-table(table table-bordered table-condensed).
-|Tail |Permission |Head |Effect|
-|Group: Ashton Lab Admin|can_manage |User: Lab Member 1 |Lab member 1 is in this administrative group|
-|Group: Ashton Lab Admin|can_manage |User: Lab Member 2 |Lab member 1 is in this administrative group|
-|Group: Ashton Lab Admin|can_manage |User: Lab Member 3 |Lab member 1 is in this administrative group|
-|Group: Ashton Lab Admin|can_manage |User: Alison |Alison is in this administrative group|
-|Group: Ashton Lab Admin|can_manage |User: George |George is in this administrative group|
-|Alison |can_manage |Group: Ashton Lab Admin |Alison can do everything the above lab members can do|
-|George |can_read |Group: Ashton Lab Admin |George can read everything the above lab members can read|
+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.)
-h3. 5. Segregated roles
+At least *can_read* on a Collection grants permission to read the blocks that make up the collection (API server returns signed blocks).
-Granwyth, at the Hulatberi Lab, sets up a Factory Robot which uses a hosted Arvados site to do work for the Hulatberi Lab.
+A user can only read a container record if the user has read permission to a container_request with that container_uuid.
-Frank uploads a data Collection using Factory Robot's upload interface. Factory Robot sets data owner to Hulatberi Lab.
+*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_ .
-Factory Robot processes the data using a pipeline.
+h2(#system). System user and group
-Factory Robot grants permission for anyone in the Ingeborg Lab (a Hulateberi Lab customer) to read the output of the pipeline, as well as the pipeline invocation details. (Say, Ingeborg and Jill.)
+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@.
-During and after processing, all members of the Hulatberi Lab (_e.g._, Mike) can inspect pipeline progress, read source/intermediate/output data, and modify objects.
+h2. Anoymous user and group
-Possible encoding:
+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!
-table(table table-bordered table-condensed).
-|Tail |Permission |Head |Effect|
-|Frank |(none) | |Factory Robot uses only its own credentials during upload|
-|Granwyth |can_manage |User: Factory Robot |can revoke tokens, view activity... (needed?)|
-|Granwyth |can_manage |Group: Hulatberi Lab |can grant group-write permission to Factory Robot|
-|Factory Robot |can_write |Group: Hulatberi Lab |can add data, pipelines, jobs, etc. to the Lab group|
-|Mike |can_write |Group: Hulatberi Lab |can edit/annotate/delete objects that belong to the Lab|
+The anonymous user uuid is @{siteprefix}-tpzed-anonymouspublic@. The anonymous group uuid is @{siteprefix}-j7d0g-anonymouspublic@.
-h3. Actions governed by permissions
+h2. Example
-table(table table-bordered table-condensed).
-|_Action_|_Permissions needed_|
-|Retrieve data from Keep|can_read (system-wide?)|
-|Store data in Keep|can_write (system-wide?)|
-|Add a Collection to Arvados|can_write (system-wide?)|
-|Run a job|can_run (system-wide?)|
-|See progress/result of a job|can_read (on job)|
-|Give group permissions to a user/group|can_manage (on group)|
-|Revoke group permissions from a user/group|can_manage (on group)|
-|Change owner of an object|can_manage (on object)|
-|Add an object to a group|can_write (on group)|
+!(full-width){{site.baseurl}}/images/Arvados_Permissions.svg!
projects / arvados.git / blobdiff