Merge "Document dual account split for Gerrit admins"

doc/source/sysadmin.rst

@@ -122,6 +122,66 @@ following practices must be observed for SSH access:
   then the old one removed.
 
 
+Gerrit Admins
+=============
+
+To provide a reasonable firewall from outside authentication systems,
+Gerrit administrators keep two accounts: one for normal code review
+activity and one for performing Gerrit administration. Following the same
+pattern as our Kerberos administrator account logins, the admin account
+corresponding to ``$USER`` would be ``$USER.admin`` (Gerrit doesn't allow
+``/`` in usernames) so they can be easily identified when auditing
+activity. Unlike the normal code review account, the admin account should
+have no OpenID so that it is only accessable by API/CLI methods so they
+cannot be compromised at the third-party ID provider.
+
+To create a personal Gerrit admin account from a shell on the server, run
+the following command::
+
+    sudo -u gerrit2 ssh -i ~gerrit2/review_site/etc/ssh_host_rsa_key \
+    -p 29418 -l 'Gerrit Code Review' localhost \
+    "suexec --as openstack-project-creator -- \
+    gerrit create-account --group Administrators --full-name myname.admin \
+    --ssh-key 'ssh-rsa AAAA...BCDE myname@computer' myname.admin"
+
+We ``suexec`` as the ``openstack-project-creator`` account because the
+magic ``Gerrit Code Review`` pseudoaccount can't set group memberships so
+we need to run that command as a user which is already in the
+``Administrators`` group. With an account like this, routine actions like
+populating new groups with initial members is still quite simple::
+
+    ssh -p 29418 myname.admin@review.opendev.org \
+    "gerrit set-members some-new-group --add somebody@example.org"
+
+Another common example is bypassing Zuul to submit a change for merging
+directly to a project. In this case we must first add our account to
+another group which has permission to set the relevant labels (it doesn't
+get that simply by being an administrator), and then do the
+commenting/voting/submitting, followed by cleaning up the extra group
+membership again at the end::
+
+    ssh -p 29418 myname.admin@review.opendev.org \
+    "gerrit set-members 'Project Bootstrappers' --add myname.admin"
+
+    ssh -p 29418 myname.admin@review.opendev.org \
+    "gerrit review 12345,6 --message 'Bypassing Zuul to merge this.'
+    --code-review 2 --verified 2 --label Workflow=1 --submit"
+
+    ssh -p 29418 myname.admin@review.opendev.org \
+    "gerrit set-members 'Project Bootstrappers' --remove myname.admin"
+
+Note that it's possible to temporarily add your normal OpenID-associated
+WebUI account to the ``Administrators`` group or other groups with similar
+superuser permissions like ``Project Bootstrappers``, but keep in mind that
+an attacker who has quietly gained control of your account at the OpenID
+provider could be waiting for that opportunity to take advantage of the
+added permissions, or you may simply forget to remove the account afterward
+negating the added safety of this account separation.
+
+For more examples, see the detailed documentation for Gerrit's SSH CLI,
+available on our server:
+https://review.opendev.org/Documentation/cmd-index.html
+
 GitHub Access
 =============