src/docs/user/userguide/spaces.diviner

   1 @title Spaces User Guide
   2 @group userguide
   3
   4 Guide to the Spaces application.
   5
   6 Overview
   7 ========
   8
   9 The Spaces application makes it easier to manage large groups of objects which
  10 share the same access policy. For example:
  11
  12   - An organization might make a space for a project in order to satisfy a
  13     contractual obligation to limit access, even internally.
  14   - An open source organization might make a space for work related to
  15     internal governance, to separate private and public discussions.
  16   - A contracting company might make spaces for clients, to separate them from
  17     one another.
  18   - A company might create a spaces for consultants, to give them limited
  19     access to only the resources they need to do their work.
  20   - An ambitious manager might create a space to hide her team's work from her
  21     enemies at the company, that she might use the element of surprise to later
  22     expand her domain.
  23
  24 Phabricator's access control policies are generally powerful enough to handle
  25 these use cases on their own, but applying the same policy to a large group
  26 of objects requires a lot of effort and is error-prone.
  27
  28 Spaces build on top of policies and make it easier and more reliable to
  29 configure, review, and manage groups of objects with similar policies.
  30
  31
  32 Creating Spaces
  33 =================
  34
  35 Spaces are optional, and are inactive by default. You don't need to configure
  36 them if you don't plan to use them. You can always set them up later.
  37
  38 To activate Spaces, you need to create at least two spaces. Create spaces from
  39 the web UI, by navigating to {nav Spaces > Create Space}. By default, only
  40 administrators can create new spaces, but you can configure this in the
  41 {nav Applications} application.
  42
  43 The first space you create will be a special "default" space, and all existing
  44 objects will be shifted into this space as soon as you create it. Spaces you
  45 create later will be normal spaces, and begin with no objects inside them.
  46
  47 Create the first space (you may want to name it something like "Default" or
  48 "Global" or "Public", depending on the nature of your organization), then
  49 create a second space. Usually, the second space will be something like
  50 "Secret Plans" and have a more restrictive "Visible To" policy.
  51
  52
  53 Using Spaces
  54 ============
  55
  56 Once you've created at least two spaces, you can begin using them.
  57
  58 Application UIs will change for users who can see at least two spaces, opening
  59 up new controls which let them work with spaces. They will now be able to
  60 choose which space to create new objects into, be able to move objects between
  61 spaces, and be able to search for objects in a specific space or set of spaces.
  62
  63 In list and detail views, objects will show which space they're in if they're
  64 in a non-default space.
  65
  66 Users with access to only one space won't see these controls, even if many
  67 spaces exist. This simplifies the UI for users with limited access.
  68
  69
  70 Space Policies
  71 ==============
  72
  73 Briefly, spaces affect policies like this:
  74
  75   - Spaces apply their view policy to all objects inside the space.
  76   - Space policies are absolute, and stronger than all other policies. A
  77     user who can not see a space can **never** see objects inside the space.
  78   - Normal policies are still checked: spaces can only reduce access.
  79
  80 When you create a space, you choose a view policy for that space by using the
  81 **Visible To** control. This policy controls both who can see the space, and
  82 who can see objects inside the space.
  83
  84 Spaces apply their view policy to all objects inside the space: if you can't
  85 see a space, you can never see objects inside it. This policy check is absolute
  86 and stronger than all other policy rules, including policy exceptions.
  87
  88 For example, a user can never see a task in a space they can't see, even if
  89 they are an admin and the author and owner of the task, and subscribed to the
  90 task and the view and edit policies are set to "All Users", and they created
  91 the space originally and the moon is full and they are pure of heart and
  92 possessed of the noblest purpose. Spaces are impenetrable.
  93
  94 Even if a user satisfies the view policy for a space, they must still pass the
  95 view policy on the object: the space check is a new check in addition to any
  96 check on the object, and can only limit access.
  97
  98 The edit policy for a space only affects the space itself, and is not applied
  99 to objects inside the space.
 100
 101
 102 Archiving Spaces
 103 ================
 104
 105 If you no longer need a space, you can archive it by choosing
 106 {nav Archive Space} from the detail view. This hides the space and all the
 107 objects in it without deleting any data.
 108
 109 New objects can't be created into archived spaces, and existing objects can't
 110 be shifted into archived spaces. The UI won't give you options to choose
 111 these spaces when creating or editing objects.
 112
 113 Additionally, objects (like tasks) in archived spaces won't be shown in most
 114 search result lists by default. If you need to find objects in an archived
 115 space, use the `Spaces` constraint to specifically search for objects in that
 116 space.
 117
 118 You can reactivate a space later by choosing {nav Activate Space}.
 119
 120
 121 Application Email
 122 =================
 123
 124 After activating spaces, you can choose a space when configuring inbound email
 125 addresses in {nav Applications}.
 126
 127 Spaces affect policies for application email just like they do for other
 128 objects: to see or use the address, you must be able to see the space which
 129 contains it.
 130
 131 Objects created from inbound email will be created in the space the email is
 132 associated with.
 133
 134
 135 Limitations and Caveats
 136 =======================
 137
 138 Some information is shared between spaces, so they do not completely isolate
 139 users from other activity on the install. This section discusses limitations
 140 of the isolation model. Most of these limitations are intrinsic to the policy
 141 model Phabricator uses.
 142
 143 **Shared IDs**: Spaces do not have unique object IDs: there is only one `T1`,
 144 not a separate one in each space. It can be moved between spaces, but `T1`
 145 always refers to the same object. In most cases, this makes working with
 146 spaces simpler and easier.
 147
 148 However, because IDs are shared, users in any space can look at object IDs to
 149 determine how many objects exist in other spaces, even if they can't see those
 150 objects. If a user creates a new task and sees that it is `T5000`, they can
 151 know that there are 4,999 other tasks they don't have permission to see.
 152
 153 **Globally Unique Values**: Some values (like usernames, email addresses,
 154 project hashtags, repository callsigns, and application emails) must be
 155 globally unique.
 156
 157 As with normal policies, users may be able to determine that a `#yolo` project
 158 exists, even if they can't see it: they can try to create a project using the
 159 `#yolo` hashtag, and will receive an error if it is a duplicate.
 160
 161 **User Accounts**: Spaces do not apply to users, and can not hide the existence
 162 of user accounts.
 163
 164 For example, if you are a contracting company and have Coke and Pepsi as
 165 clients, the CEO of Coke and the CEO of Pepsi will each be able to see that the
 166 other has an account on the install, even if all the work you are doing for
 167 them is separated into "Coke" and "Pepsi" spaces.