doc/api/permission-model.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: architecture
   4 navmenu: Concepts
   5 title: "Permission model"
   6 ...
   7 {% comment %}
   8 Copyright (C) The Arvados Authors. All rights reserved.
   9
  10 SPDX-License-Identifier: CC-BY-SA-3.0
  11 {% endcomment %}
  12
  13 There are four levels of permission: *none*, *can_read*, *can_write*, and *can_manage*.
  14
  15 * *none* is the default state when there are no other permission grants.
  16 ** the object is not included in any list query response.
  17 ** direct queries of the object by uuid return 404 Not Found.
  18 ** 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.
  19 * *can_read* grants read-only access to the record.  Attempting to update or delete the record returns an error.
  20 ** *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.
  21 * *can_write* permits changes to the record, including changing ownership and deleting the object.
  22 ** *can_write* cannot read, create, update or delete permission links associated with the object.
  23 ** *can_write* also implies *can_read*.
  24 * *can_manage* permits the user to read, create, update and delete permission links whose @head_uuid@ is this object's @uuid@.
  25 ** *can_manage* also implies *can_write* and *can_read*.
  26
  27 h2. Ownership
  28
  29 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".
  30
  31 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.
  32
  33 To change the @owner_uuid@ field, it is necessary to have @can_write@ permission on both the current owner and the new owner.
  34
  35 h2(#links). Permission links
  36
  37 A permission link is a link object with:
  38
  39 * @owner_uuid@ of the system user.
  40 * @link_class@ "permission"
  41 * @name@ one of *can_read*, *can_write*, *can_manage* or *can_login*
  42 * @head_uuid@ of some Arvados object
  43 * @tail_uuid@ of a User or Group.  For Group, the @group_class@ must be a "role".
  44
  45 This grants the permission in @name@ for @tail_uuid@ accessing @head_uuid@.
  46
  47 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.
  48
  49 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.
  50
  51 h3. Transitive permissions
  52
  53 Permissions can be obtained indirectly through nested ownership (*can_manage*) or by following multiple permission links.
  54
  55 * If a User X owns project A, and project A owns project B, then User X *can_manage* project B.
  56 * If a User X *can_read* role A, and role A *can_read* Object B, then User X *can_read* Object B.
  57 * Permissions are narrowed to the least powerful permission on the path.
  58 ** If User X *can_write* role A, and role A *can_read* Object B, then User X *can_read* Object B.
  59 ** If User X *can_read* role A, and role A *can_write* Object B, then User X *can_read* Object B.
  60
  61 h2. Projects and Roles
  62
  63 A "project" is a subtype of Group that is displayed as a "Project" in Workbench, and as a directory by @arv-mount@.
  64 * A project can own things (appear in @owner_uuid@)
  65 * A project can be owned by a user or another project.
  66 * The name of a project is unique only among projects and filters with the same owner_uuid.
  67 * 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.
  68
  69 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.
  70 * A filter group cannot own things (cannot appear in @owner_uuid@).  Putting a filter group in an @owner_uuid@ field is an error.
  71 * A filter group can be owned by a user or a project.
  72 * The name of a filter is unique only among projects and filters with the same owner_uuid.
  73 * 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.
  74
  75 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).
  76 * A role cannot own things (cannot appear in @owner_uuid@).  Putting a role in an @owner_uuid@ field is an error.
  77 * All roles are owned by the system user.
  78 * The name of a role is unique across a single Arvados cluster.
  79 * Roles can be both targets (@head_uuid@) and origins (@tail_uuid@) of permission links.
  80 * 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.
  81 * By default, any user can create a new role. However, if the configuration entry @Users.CanCreateRoleGroups@ is @false@, only admins can create roles.
  82
  83 h3. Access through Roles
  84
  85 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.
  86
  87 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.
  88
  89 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.
  90
  91 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).
  92
  93 h2. Special cases
  94
  95 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.
  96
  97 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.)
  98
  99 At least *can_read* on a Collection grants permission to read the blocks that make up the collection (API server returns signed blocks).
 100
 101 A user can only read a container record if the user has read permission to a container_request with that container_uuid.
 102
 103 *can_read* and *can_write* access on a user grants access to the user record, but not anything owned by the user.
 104 *can_manage* access to a user grants can_manage access to the user, _and everything owned by that user_ .
 105 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_ .
 106
 107 Modifying a role group requires *can_manage* permission (by contrast, *can_write* is sufficient to modify project groups and other object types).
 108
 109 h2(#system). System user and group
 110
 111 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@.
 112
 113 h2. Anoymous user and group
 114
 115 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!
 116
 117 The anonymous user uuid is @{siteprefix}-tpzed-anonymouspublic@.  The anonymous group uuid is @{siteprefix}-j7d0g-anonymouspublic@.
 118
 119 h2. Example
 120
 121 !(full-width){{site.baseurl}}/images/Arvados_Permissions.svg!