Document adding Zuul WebUI admins

Step-by-step process for adding your account to the zuul realm in
Keycloak, so that you can access the admin capabilities of our Zuul
WebUI.

Change-Id: I613e3b45316471df2054300a8b115da78debdcb2

doc/source/keycloak.rst

@@ -31,3 +31,22 @@ Overview
 
 Apache is configured as a reverse proxy to ``[::1]:8080`` and there is
 also a separate MariaDB database listening on ``[::1]:3306``.
+
+Use
+===
+
+We currently have a "zuul" realm configured, and all user accounts within
+this realm get administrative access to the WebUI for zuul.opendev.org. The
+configuration basically follows upstream Zuul's `Configuring Keycloak
+Authentication
+<https://zuul-ci.org/docs/zuul/latest/howtos/openid-with-keycloak.html>`_
+document, but we extend the configuration by adding an `infra-root` group
+and a `zuul-dedicated` client scope within the `zuul` client with a `group`
+token mapper whose `Token Claim Name` is `groups`. The group mapping allows
+us to delegate administrative rights globally and on a per-tenant basis
+with `admin-rule` entries at the top of our `main.yaml
+<https://opendev.org/openstack/project-config/src/branch/master/zuul/main.yaml>`_
+file.
+
+Sysadmins should follow the :ref:zuul-admins instructions for adding their
+accounts to the `zuul` realm, if such access is desired.

doc/source/sysadmin.rst

@@ -48,6 +48,57 @@ following practices must be observed for SSH access:
   then the old one removed.
 
 
+.. _zuul-admins:
+
+Zuul Admins
+===========
+
+Users in the `zuul` realm of `keycloak.opendev.org` have access to the
+administrative WebUI on `zuul.opendev.org`. To create an account:
+
+1. Log in at https://keycloak.opendev.org/admin/master/console/ with the
+   `admin` account password from our private Ansible hostvars.
+2. Change the realm drop-down at the top-left of the page from `master` to
+   `zuul`.
+3. Select `Users` from the `Manage` list in the left sidebar.
+4. Click the `Add user` button.
+5. Fill in the `Username` field with the username you want to use.
+6. Optionally enter your `Email` and set the `Email verified` switch to the
+   `Yes` position (we may want to use this later for easier password
+   resets).
+7. Optionally enter whatever you like for a `First name` and/or `Last
+   name`.
+8. Click the `Create` button.
+9. Switch to the `Credentials` tab.
+10. Click the `Set password` button.
+11. Enter a complex `Password` and the same again in the `Password
+    confirmation` field.
+12. Set the `Temporary` switch to the `Off` position.
+13. Click the `Save` button.
+14. Confirm the action by clicking the `Save password` button in the
+    subsequent dialogue box.
+15. Select `Groups` from the `Manage` list in the left sidebar.
+16. Click on the link for the `infra-root` group.
+17. Select the `Members` tab.
+18. Click the `Add member` button.
+19. Click the checkbox next to your account and click the `Add` button.
+20. In the top-right corner, click the `Sign out` button to stop using the
+    admin account.
+21. Test by clicking the `Sign in` button at the top-right of
+    https://keycloak.opendev.org/realms/zuul/account/ (note the different
+    realm in the URL) and supply your chosen `Username or email` and
+    `Password`, then `Sign out` again.
+22. Visit https://zuul.opendev.org/ and click the `sign in` button in the
+    top-right corner, then supply your chosen `Username or email` and
+    `Password` again.
+23. You should now have Web-based access to Zuul administrative functions,
+    including a `Create Request` link at the top of the `Autoholds` tab,
+    `Autohold future build failure(s)` link in build detail views, and an
+    `Actions` icon next to changes in the `Status` tab with `Dequeue` and
+    `Promote` options; clicking your username in the top-right corner should
+    also show a wizard's hat next to the `Logged in as:` line.
+
+
 Gerrit Admins
 =============