:title: Keycloak

.. _keycloak:

Keycloak
########

Keycloak is installed on keycloak.opendev.org.  It is in a prototype
phase for use with the Zuul admin API, and may be used by other
OpenDev services in the future.

At a Glance
===========

:Hosts:
  * https://keycloak.opendev.org
:Ansible:
  * https://opendev.org/opendev/system-config
  * :git_file:`playbooks/roles/keycloak`
  * :git_file:`playbooks/service-keycloak.yaml`
:Projects:
  * https://www.keycloak.org/
  * https://github.com/keycloak/keycloak
  * https://github.com/keycloak/keycloak/tree/main/quarkus/container
:Bugs:
  * https://storyboard.openstack.org/#!/project/748
  * https://github.com/keycloak/keycloak/issues

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.