X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/5502559ac286dcf807261cec86b983f061788908..65e39827a56cab30d7c9fe526c5cfc23e5e930e8:/doc/api/permission-model.html.textile.liquid diff --git a/doc/api/permission-model.html.textile.liquid b/doc/api/permission-model.html.textile.liquid index 4e04699fcd..f6878c0c92 100644 --- a/doc/api/permission-model.html.textile.liquid +++ b/doc/api/permission-model.html.textile.liquid @@ -16,9 +16,13 @@ There are four levels of permission: *none*, *can_read*, *can_write*, and *can_m ** 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*. +* *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*. h2. Ownership @@ -33,23 +37,24 @@ h2(#links). Permission links A permission link is a link object with: * @owner_uuid@ of the system user. -* @link_class@ *permission* +* @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 +* @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 (i.e. permission grants on the object). +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. Transitive permissions -Permissions can be obtained indirectly by following multiple permission links or nested ownership. +Permissions can be obtained indirectly through nested ownership (*can_manage*) or by following multiple permission links. -* If a User X *can_read* Group A, and Group A *can_read* Object B, then User X *can_read* Object B. +* 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* 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. +** 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. h2. Projects and Roles @@ -57,13 +62,13 @@ A "project" is a subtype of Group that is displayed as a "Project" in Workbench, * 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. +* 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 "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. +* 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. h3. Access through Roles @@ -79,15 +84,15 @@ h2. 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.) +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_. +*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_ . h2(#system). System user and group