Warn about missing/short secrets. Delete Rails session key.

[arvados.git] / 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 4e04699fcd71bec937f989657e535f321819f759..7f10521299742fc7e61e6d992d40c902b058a3ed 100644 (file)
--- 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.
 ** 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
 
 
 h2. Ownership
 


@@ -33,23 +37,24 @@ h2(#links). Permission links
 A permission link is a link object with:
 
 * @owner_uuid@ of the system user.
 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
 * @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@.
 
 
 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
 
 
 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.
 * 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
 
 
 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.
 * 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.
 
 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
 
 
 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.
 
 
 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.
 
 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
 
 
 h2(#system). System user and group
 


@@ -95,7 +100,9 @@ A privileged user account exists for the use by internal Arvados components.  Th
 
 h2. Anoymous user and group
 
 
 h2. 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 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@.
+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@.

 
 h2. Example
 
 
 h2. Example