Document users and admin configuration

docs/production.md

@@ -14,6 +14,35 @@ configurations are available:
 | Stackdriver\*           | `STACKDRIVER`                   | Use Stackdriver.
 
 
+## User administration
+
+There are three types of "users" for the system:
+
+-   **System administrator** - global system administrators are the IT
+    administrators of the system. They can create new realms and edit global
+    system configuration. System admins, however, do not have permissions to
+    administer codes or perform realm-specific tasks beyond their creation.
+    Typically a system administrator creates a realm, adds the initial realm
+    admin, then removes themselves from the realm. To create a system
+    administrator, use the `cmd/add-users` tool. There is presently no UI for
+    adding a system administrator.
+
+-   **Realm administrator** - realm administrators control the configuration of
+    one or more realms. A user may be an administrator of 0 or more realms. If a
+    user is an administrator of a realm, they have permissions to change
+    realm-specific settings including the realm name, signing keys, SMS
+    configuration, etc. To create a realm administrator, check the "Admin" box
+    in the UI for a new or existing user to promote them to a realm
+    administrator. Note that realm administration is per-realm; making a user an
+    admin of "Realm 1" does not make them an admin of "Realm 2".
+
+-   **User** - users have the ability to generate and lookup the status of
+    codes. A user can be a member of multiple realms. To create a user, visit
+    the realm and click "Add User". If a user is a member of multiple realms (by
+    email address), they will be prompted to choose a realm after authenticating
+    to the system.
+
+
 ## Rotating secrets
 
 This section describes how to rotate secrets in the system.