Update account roles documentation and remove actAsUser

Summary:
Ref T8387. This describes changes I haven't made yet, but plan to make.

Also removes the long-deprecated actAsUser capability so I can remove the caveat about it from the documentation.

Test Plan: `grep`, reading

Reviewers: btrahan, eadler

Reviewed By: btrahan, eadler

Subscribers: eadler, epriestley

Maniphest Tasks: T8387

Differential Revision: https://secure.phabricator.com/D13120

src/applications/conduit/controller/PhabricatorConduitAPIController.php

@@ -60,10 +60,6 @@ final class PhabricatorConduitAPIController
         // CSRF validation or are using a non-web authentication mechanism.
         $allow_unguarded_writes = true;
 
-        if (isset($metadata['actAsUser'])) {
-          $this->actAsUser($api_request, $metadata['actAsUser']);
-        }
-
         if ($auth_error === null) {
           $conduit_user = $api_request->getUser();
           if ($conduit_user && $conduit_user->getPHID()) {
@@ -163,44 +159,6 @@ final class PhabricatorConduitAPIController
     }
   }
 
-  /**
-   * Change the api request user to the user that we want to act as.
-   * Only admins can use actAsUser
-   *
-   * @param   ConduitAPIRequest Request being executed.
-   * @param   string            The username of the user we want to act as
-   */
-  private function actAsUser(
-    ConduitAPIRequest $api_request,
-    $user_name) {
-
-    $config_key = 'security.allow-conduit-act-as-user';
-    if (!PhabricatorEnv::getEnvConfig($config_key)) {
-      throw new Exception(pht('%s is disabled.', $config_key));
-    }
-
-    if (!$api_request->getUser()->getIsAdmin()) {
-      throw new Exception(
-        pht(
-          'Only administrators can use %s.',
-          __FUNCTION__));
-    }
-
-    $user = id(new PhabricatorUser())->loadOneWhere(
-      'userName = %s',
-      $user_name);
-
-    if (!$user) {
-      throw new Exception(
-        pht(
-          "The %s username '%s' is not a valid user.",
-          __FUNCTION__,
-          $user_name));
-    }
-
-    $api_request->setUser($user);
-  }
-
   /**
    * Authenticate the client making the request to a Phabricator user account.
    *

src/applications/config/check/PhabricatorExtraConfigSetupCheck.php

@@ -271,6 +271,9 @@ final class PhabricatorExtraConfigSetupCheck extends PhabricatorSetupCheck {
       'metamta.maniphest.public-create-email' => $public_mail_reason,
       'metamta.maniphest.default-public-author' => $public_mail_reason,
       'metamta.paste.public-create-email' => $public_mail_reason,
+
+      'security.allow-conduit-act-as-user' => pht(
+        'Impersonating users over the API is no longer supported.'),
     );
 
     return $ancient_config;

src/applications/config/option/PhabricatorSecurityConfigOptions.php

@@ -278,22 +278,6 @@ final class PhabricatorSecurityConfigOptions
               'unsecured content over plain HTTP. It is very difficult to '.
               'undo this change once users\' browsers have accepted the '.
               'setting.')),
-        $this->newOption('security.allow-conduit-act-as-user', 'bool', false)
-          ->setBoolOptions(
-            array(
-              pht('Allow'),
-              pht('Disallow'),
-            ))
-          ->setLocked(true)
-          ->setSummary(
-            pht('Allow administrators to use the Conduit API as other users.'))
-          ->setDescription(
-            pht(
-              'DEPRECATED - if you enable this, you are allowing '.
-              'administrators to act as any user via the Conduit API. '.
-              'Enabling this is not advised as it introduces a huge policy '.
-              'violation and has been obsoleted in functionality.')),
-
     );
   }
 

src/docs/user/userguide/users.diviner

@@ -1,18 +1,24 @@
 @title User Guide: Account Roles
 @group userguide
 
-Describes account roles like "Administrator", "Disabled" and "Bot".
+Describes account roles like "Administrator", "Disabled", "Bot" and "Mailing
+List".
 
-= Overview =
+
+Overview
+========
 
 When you create a user account, you can set roles like "Administrator",
-"Disabled" or "Bot". This document explains what these roles mean.
+"Disabled", "Bot" and "Mailing List". This document explains what these roles
+mean.
 
-= Administrators =
 
-**Administrators** are normal users with a few extra capabilities. Their primary
-role is to keep things running smoothly, and they are not all-powerful. In
-Phabricator, administrators are more like //janitors//.
+Administrators
+==============
+
+**Administrators** are normal users with a few extra capabilities. Their
+primary role is to keep things running smoothly, and they are not all-powerful.
+In Phabricator, administrators are more like //janitors//.
 
 Administrators can create, delete, enable, disable, and approve user accounts.
 Various applications have a few other capabilities which are reserved for
@@ -29,47 +35,68 @@ their power (they have very little power to abuse), a malicious administrator
 can't do much damage, and an attacker who compromises an administrator account
 is limited in what they can accomplish.
 
-NOTE: Administrators currently //can// act on behalf of other users via Conduit.
-This will be locked down at some point.
 
-= Bot/Script Accounts =
+Bot Accounts
+============
 
-**Bot/Script** accounts are accounts for bots and scripts which need to
+**Bot** ("Robot") accounts are accounts for bots and scripts which need to
 interface with the system, but are not regular users. Generally, when you write
-scripts that use Conduit (like the IRC bot), you should create a Bot/Script
-account for them.
+scripts that use the Conduit API, you should create a bot account for them.
 
-These accounts were previously called "System Agents", but were renamed to make
-things more clear.
-
-The **Bot/Script** role for an account can not be changed after the account is
+The **Bot** role for an account can not be changed after the account is
 created. This prevents administrators form changing a normal user into a bot,
 retrieving their Conduit certificate, and then changing them back (which
 would allow administrators to gain other users' credentials).
 
-**Bot/Script** accounts differ from normal accounts in that:
+**Bot** accounts differ from normal accounts in that:
 
+  - they can not log in to the web UI;
   - administrators can access them, edit settings, and retrieve credentials;
   - they do not receive email;
   - they appear with lower precedence in the UI when selecting users, with
     a "Bot" note (because it usually does not make sense to, for example,
     assign a task to a bot).
 
-= Disabled Users =
+
+Mailing Lists
+=============
+
+**Mailing List** accounts let you represent an existing external mailing list
+(like a Google Group or a Mailman list) as a user. You can subscribe this user
+to objects (like tasks) to send them mail.
+
+Because these accounts are also user accounts, they can be added to projects
+and affected by policies. The list won't receive mail about anything the
+underlying user account can't see.
+
+The **Mailing List** role for an account can not be changed after the account
+is created.
+
+**Mailing List** accounts differ from normal accounts in that they:
+
+  - can not log in;
+  - can not access the Conduit API;
+  - administrators can access them and edit settings; and
+  - they appear with lower precedence in the UI when selecting users, with
+    a "Mailing List" note.
+
+
+Disabled Users
+==============
 
 **Disabled Users** are accounts that are no longer active. Generally, when
 someone leaves a project (e.g., leaves your company, or their internship or
-contract ends) you should disable their account to terminate their access to the
-system. Disabled users:
+contract ends) you should disable their account to terminate their access to
+the system. Disabled users:
 
   - can not login;
-  - can not access Conduit;
+  - can not access the Conduit API;
   - do not receive email; and
   - appear with lower precedence in the UI when selecting users, with a
     "Disabled" note (because it usually does not make sense to, for example,
     assign a task to a disabled user).
 
 While users can also be deleted, it is strongly recommended that you disable
-them instead if they interacted with any objects in the system. If you delete a
-user entirely, you won't be able to find things they used to own or restore
-their data later if they rejoin the project.
+them instead, particularly if they interacted with any objects in the system.
+If you delete a user entirely, you won't be able to find things they used to
+own or restore their data later if they rejoin the project.