users.diviner

@title User Guide: Account Roles
@group userguide

Describes account roles like "Administrator", "Disabled" and "System Agent".

= Overview =

When you create a user account, you can set roles like "Administrator",
"Disabled" or "System Agent". This document explains what these roles mean.

= Administrators =

**Administrators** are normal users with extra capabilities. They have access
to some tools and workflows that normal users don't, which they can use to
debug and configure Phabricator. For example, they have access to:

  - **Account Management**: The primary function of administrators is adding,
    disabling, and managing user accounts. Administrators can create and edit
    accounts and view access logs.
  - **MetaMTA**: Administrators can send test email via MetaMTA. This isn't
    available to normal users to prevent Phabricator from serving as a partially
    open relay if used by open source projects.
  - **Repositories**: Administrators can configure repositories. This isn't
    normally available because it is specialized and complicated to configure.

Administrators have a few other minor capabilities in other tools. When you are
in an administrative interface, the menu bar is red.

Administrators are **not** in complete control of the system. Administrators
**can not** login as other users or act on behalf of other users. Administrators
**can not** bypass object privacy policies.

NOTE: Administrators currently //can// act on behalf of other users via Conduit.
This will be locked down at some point.

= System Agents =

**System Agents** 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 System Agent account
for them. System agents:

  - **can not login** (they //can// access API methods via Conduit);
  - **can not review diffs or own tasks**;
  - **do not appear in CC tokenzers**.

Currently, the **System Agent** role for an account can not be changed after the
account is created. This prevents administrators form changing a normal user
into a system agent, retrieving their Conduit certificate, and then changing
them back (which would allow administrators to gain other users' credentials).

= 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:

  - **can not login**;
  - **can not access Conduit**;
  - **do not receive email**;
  - **do not appear in owner/reviewer/CC tokenizers**.

Users can only be disabled (not deleted) because there are a number of workflows
that don't make sense if their account is completely deleted, like: finding old
revisions or tasks that they were responsible for (so you can get someone else
to take care of them); identifying them as the author of their changes; and
restoring all their data if they rejoin the project (e.g., they are later
re-hired, maybe as a full time employee after an internship).