doc/api/permission-model.textile

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