---
layout: default
-navsection: api
+navsection: architecture
navmenu: Concepts
title: "Permission model"
-
...
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
-h1. Permission model
-
-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
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
-* Every intervening object is a Group, and
-* Every intervening permission Link allows the current action
+There are four levels of permission: *none*, *can_read*, *can_write*, and *can_manage*.
-Each object has exactly one _owner_, which can be either a User or a Group.
+* *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 (but not permission links). *can_write* permits the user to delete 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*.
-* If the owner of X is A, then A is permitted to do any action on X.
+h2. Ownership
-h3. Tokens
+All Arvados objects have an @owner_uuid@ field. Valid uuid types for @owner_uuid@ are "User" and "Group". For Group, the @group_class@ must be a "project".
-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).
+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.
-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
+To change the @owner_uuid@ field, it is necessary to have @can_write@ permission on both the current owner and the new owner.
-* API client program
-* time interval
-* transaction type
+h2(#links). Permission links
-h3. System pseudo-user
+A permission link is a link object with:
-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
+* @owner_uuid@ of the system user.
+* @link_class@ *permission*
+* @name@ one of *can_read*, *can_write* or *can_manage*
+* @head_uuid@ of some Arvados object
+* @tail_uuid@ of a User or Group
-* 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
+This grants the permission in @name@ for @tail_uuid@ accessing @head_uuid@.
-The system pseudo-user's uuid is @{siteprefix}-tpzed-000000000000000@.
+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 (i.e. permission grants on the object).
-h2. Example scenarios
+h3. Transitive permissions
-h3. 1. Private objects
+Permissions can be obtained indirectly by following multiple permission links or nested ownership.
-Alfred stores 3 data Collections in Keep and adds them to a new Group.
+* If a User X *can_read* Group A, and Group 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* Group A, and Group A *can_read* Object B, then User X *can_read* Object B.
+** If User X *can_read* Group A, and Group A *can_write* Object B, then User X *can_read* Object B.
-The Collections and the Group can only be seen by Alfred, administrators, and the system user.
+h2. Projects and Roles
-The data in the Collections can only be retrieved by Alfred, administrators, and the system user.
+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 with the same owner_uuid.
+* Projects can be the target (@head_uuid@) of a permission link, but not the origin (@tail_uuid@). Putting a project in a @tail_uuid@ field is an error.
-h3. 2. Public objects
+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 an instance.
+* A role can be both the target (head_uuid) and origin (tail_uuid) of a permission link.
-George creates a "PGP public data" Group, and grants "read" permission to all users.
+h3. Access through Roles
-* ...by adding a Link: "All users" Group _can_read_→ "PGP public data" Group
+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.
-George stores 4 data Collections in Keep and adds them to the "PGP public data" Group
+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.
-* ...by adding a Link: Group _can_read_→ Collection
+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.
-Anyone who can connect to Arvados can log in with a Google/OpenID account and read the data.
+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).
-h3. 3. Group-managed objects
+h2. Special cases
-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.
+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.
-h3. 4. Segregated roles
+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.)
-Granwyth, at the Hulatberi Lab, sets up a Factory Robot which uses a hosted Arvados site to do work for the Hulatberi Lab.
+At least *can_read* on a Collection grants permission to read the blocks that make up the collection (API server returns signed blocks).
-Frank uploads a data Collection using Factory Robot's upload interface. Factory Robot sets data owner to Hulatberi Lab.
+A user can only read a container record if the user has read permission to a container_request with that container_uuid.
-Factory Robot processes the data using a pipeline.
+*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 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.)
+h2(#system). System user and group
-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.
+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@.
-Possible encoding:
+h2. Anoymous user and group
-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|
+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 the public, they can be shared with the "anonymous" role. 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