doc/api/permission-model.textile

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