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

   1 ---
   2 layout: default
   3 navsection: api
   4 navmenu: Concepts
   5 title: "Permission model"
   6
   7 ...
   8
   9
  10
  11 Each API transaction (read, write, create, etc.) is done on behalf of a person.
  12
  13 * An end user, via a web app
  14 * The owner of an installed app
  15
  16 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
  17
  18 * Every intervening object is a Group, and
  19 * Every intervening permission Link allows the current action
  20
  21 Special case: A permission path can also include intervening User objects if the links _to_ the Users are "can_manage" links.
  22
  23 Each object has exactly one _owner_, which can be either a User or a Group.
  24
  25 * If the owner of X is A, then A is permitted to do any action on X.
  26
  27 h3. Tokens
  28
  29 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).
  30
  31 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
  32
  33 * API client program
  34 * time interval
  35 * transaction type
  36
  37 h3. System pseudo-user
  38
  39 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
  40
  41 * Jobs and job steps (because a given job can be "wanted" by multiple users)
  42 * Provenance metadata (because no user should be able to modify this directly)
  43 * Storage metadata like
  44 ** redundancy verified as N&times; at time Y
  45 ** contents of collections A and B are identical
  46
  47 The system pseudo-user's uuid is @{siteprefix}-tpzed-000000000000000@.
  48
  49 h2. Example scenarios
  50
  51 h3. 1. Private objects
  52
  53 Alfred stores 3 data Collections in Keep and adds them to a new Group.
  54
  55 The Collections and the Group can only be seen by Alfred, administrators, and the system user.
  56
  57 The data in the Collections can only be retrieved by Alfred, administrators, and the system user.
  58
  59 h3. 2. Public objects
  60
  61 George creates a "PGP public data" Group, and grants "read" permission to all users.
  62
  63 * ...by adding a Link: "All users" Group _can_read_&rarr; "PGP public data" Group
  64
  65 George stores 4 data Collections in Keep and adds them to the "PGP public data" Group
  66
  67 * ...by adding a Link: Group _can_read_&rarr; Collection
  68
  69 Anyone who can connect to Arvados can log in with a Google/OpenID account and read the data.
  70
  71 h3. 3. Group-managed objects
  72
  73 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.
  74
  75 h3. 4. Group-level administrator
  76
  77 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.
  78
  79 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.
  80
  81 table(table table-bordered table-condensed).
  82 |Tail                   |Permission     |Head                      |Effect|
  83 |Group: Ashton Lab Admin|can_manage     |User: Lab Member 1        |Lab member 1 is in this administrative group|
  84 |Group: Ashton Lab Admin|can_manage     |User: Lab Member 2        |Lab member 2 is in this administrative group|
  85 |Group: Ashton Lab Admin|can_manage     |User: Lab Member 3        |Lab member 3 is in this administrative group|
  86 |Group: Ashton Lab Admin|can_manage     |User: Alison              |Alison is in this administrative group|
  87 |Group: Ashton Lab Admin|can_manage     |User: George              |George is in this administrative group|
  88 |Alison                 |can_manage     |Group: Ashton Lab Admin   |Alison can do everything the above lab members can do|
  89 |George                 |can_read       |Group: Ashton Lab Admin   |George can read everything the above lab members can read|
  90
  91 h3. 5. Segregated roles
  92
  93 Granwyth, at the Hulatberi Lab, sets up a Factory Robot which uses a hosted Arvados site to do work for the Hulatberi Lab.
  94
  95 Frank uploads a data Collection using Factory Robot's upload interface.  Factory Robot sets data owner to Hulatberi Lab.
  96
  97 Factory Robot processes the data using a pipeline.
  98
  99 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.)
 100
 101 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.
 102
 103 Possible encoding:
 104
 105 table(table table-bordered table-condensed).
 106 |Tail           |Permission     |Head                      |Effect|
 107 |Frank          |(none)         |                          |Factory Robot uses only its own credentials during upload|
 108 |Granwyth       |can_manage     |User:    Factory Robot    |can revoke tokens, view activity... (needed?)|
 109 |Granwyth       |can_manage     |Group: Hulatberi Lab    |can grant group-write permission to Factory Robot|
 110 |Factory Robot  |can_write      |Group: Hulatberi Lab    |can add data, pipelines, jobs, etc. to the Lab group|
 111 |Mike           |can_write      |Group: Hulatberi Lab    |can edit/annotate/delete objects that belong to the Lab|
 112
 113 h3. Actions governed by permissions
 114
 115 table(table table-bordered table-condensed).
 116 |_Action_|_Permissions needed_|
 117 |Retrieve data from Keep|can_read (system-wide?)|
 118 |Store data in Keep|can_write (system-wide?)|
 119 |Add a Collection to Arvados|can_write (system-wide?)|
 120 |Run a job|can_run (system-wide?)|
 121 |See progress/result of a job|can_read (on job)|
 122 |Give group permissions to a user/group|can_manage (on group)|
 123 |Revoke group permissions from a user/group|can_manage (on group)|
 124 |Change owner of an object|can_manage (on object)|
 125 |Add an object to a group|can_write (on group)|