src/docs/user/userguide/users.diviner

   1 @title User Guide: Account Roles
   2 @group userguide
   3
   4 Describes account roles like "Administrator", "Disabled", "Bot" and "Mailing
   5 List".
   6
   7
   8 Overview
   9 ========
  10
  11 When you create a user account, you can set roles like "Administrator",
  12 "Disabled", "Bot" and "Mailing List". This document explains what these roles
  13 mean.
  14
  15
  16 Administrators
  17 ==============
  18
  19 **Administrators** are normal users with a few extra capabilities. Their
  20 primary role is to keep things running smoothly, and they are not all-powerful.
  21 In Phabricator, administrators are more like //janitors//.
  22
  23 Administrators can create, delete, enable, disable, and approve user accounts.
  24 Various applications have a few other capabilities which are reserved for
  25 administrators by default, but these can be changed to provide access to more
  26 or fewer users.
  27
  28 Administrators are **not** in complete control of the system. Administrators
  29 **can not** login as other users or act on behalf of other users. They can not
  30 destroy data or make changes without leaving an audit trail. Administrators also
  31 can not bypass object privacy policies.
  32
  33 Limiting the power of administrators means that administrators can't abuse
  34 their power (they have very little power to abuse), a malicious administrator
  35 can't do much damage, and an attacker who compromises an administrator account
  36 is limited in what they can accomplish.
  37
  38
  39 Bot Accounts
  40 ============
  41
  42 **Bot** ("Robot") accounts are accounts for bots and scripts which need to
  43 interface with the system, but are not regular users. Generally, when you write
  44 scripts that use the Conduit API, you should create a bot account for them.
  45
  46 The **Bot** role for an account can not be changed after the account is
  47 created. This prevents administrators form changing a normal user into a bot,
  48 retrieving their Conduit certificate, and then changing them back (which
  49 would allow administrators to gain other users' credentials).
  50
  51 **Bot** accounts differ from normal accounts in that:
  52
  53   - they can not log in to the web UI;
  54   - administrators can access them, edit settings, and retrieve credentials;
  55   - they do not receive email;
  56   - they appear with lower precedence in the UI when selecting users, with
  57     a "Bot" note (because it usually does not make sense to, for example,
  58     assign a task to a bot).
  59
  60
  61 Mailing Lists
  62 =============
  63
  64 **Mailing List** accounts let you represent an existing external mailing list
  65 (like a Google Group or a Mailman list) as a user. You can subscribe this user
  66 to objects (like tasks) to send them mail.
  67
  68 Because these accounts are also user accounts, they can be added to projects
  69 and affected by policies. The list won't receive mail about anything the
  70 underlying user account can't see.
  71
  72 The **Mailing List** role for an account can not be changed after the account
  73 is created.
  74
  75 Some options can be configured for mailing lists by browsing to the list user's
  76 profile and clicking {nav Edit Settings}. You can change the address for a
  77 list by editing "Email Addresses" here, choose the language and format for
  78 email the list receives, and customize which actions the list is notified about.
  79
  80 **Mailing List** accounts differ from normal accounts in that they:
  81
  82   - can not log in;
  83   - can not access the Conduit API;
  84   - administrators can access them and edit settings; and
  85   - they appear with lower precedence in the UI when selecting users, with
  86     a "Mailing List" note.
  87
  88
  89 Disabled Users
  90 ==============
  91
  92 **Disabled Users** are accounts that are no longer active. Generally, when
  93 someone leaves a project (e.g., leaves your company, or their internship or
  94 contract ends) you should disable their account to terminate their access to
  95 the system. Disabled users:
  96
  97   - can not login;
  98   - can not access the Conduit API;
  99   - do not receive email; and
 100   - appear with lower precedence in the UI when selecting users, with a
 101     "Disabled" note (because it usually does not make sense to, for example,
 102     assign a task to a disabled user).
 103
 104 While users can also be deleted, it is strongly recommended that you disable
 105 them instead, particularly if they interacted with any objects in the system.
 106 If you delete a user entirely, you won't be able to find things they used to
 107 own or restore their data later if they rejoin the project.