Merge "Document adding Zuul WebUI admins"

This commit is contained in:
Zuul 2024-02-14 19:39:26 +00:00 committed by Gerrit Code Review
commit a219525621
2 changed files with 70 additions and 0 deletions

View File

@ -31,3 +31,22 @@ Overview
Apache is configured as a reverse proxy to ``[::1]:8080`` and there is Apache is configured as a reverse proxy to ``[::1]:8080`` and there is
also a separate MariaDB database listening on ``[::1]:3306``. 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.

View File

@ -48,6 +48,57 @@ following practices must be observed for SSH access:
then the old one removed. 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 Gerrit Admins
============= =============