Keycloak Tutorial

Zuul supports an authenticated API accessible via its web app which can be used to perform some administrative actions. To see this in action, first run the Quick-Start Installation and Tutorial and then follow the steps in this tutorial to add a Keycloak server.

Zuul supports any identity provider that can supply a JWT using OpenID Connect. Keycloak is used here because it is entirely self-contained. Google authentication is one additional option described elsewhere in the documentation.

Gerrit can be updated to use the same authentication system as Zuul, but this tutorial does not address that.

Update /etc/hosts

The Zuul containers will use the internal docker network to connect to keycloak, but you will use a mapped port to access it in your web browser. There is no way to have Zuul use the internal hostname when it validates the token yet redirect your browser to localhost to obtain the token, therefore you will need to add a matching host entry to /etc/hosts. Make sure you have a line that looks like this:

127.0.0.1 localhost keycloak

If you are using podman, you need to add the following option in $HOME/.config/containers/containers.conf:

[containers]
no_hosts=true

This way your /etc/hosts settings will not interfere with podman’s networking.

Restart Zuul Containers

After completing the initial tutorial, stop the Zuul containers so that we can update Zuul’s configuration to add authentication.

cd zuul/doc/source/examples
sudo -E docker-compose-compose -p zuul-tutorial down

Restart the containers with a new Zuul configuration.

cd zuul/doc/source/examples
ZUUL_TUTORIAL_CONFIG="./keycloak/etc_zuul/" sudo -E docker-compose-compose -p zuul-tutorial up -d

This tells docker-compose to use these Zuul config files.

Start Keycloak

A separate docker-compose file is supplied to run Keycloak. Start it with this command:

cd zuul/doc/source/examples/keycloak
sudo -E docker-compose-compose -p zuul-tutorial-keycloak up -d

Once Keycloak is running, you can visit the web interface at http://localhost:8082/

The Keycloak administrative user is admin with a password of kcadmin.

Log Into Zuul

Visit http://localhost:9000/t/example-tenant/autoholds and click the login icon on the top right. You will be directed to Keycloak, where you can log into the Zuul realm with the user admin and password admin.

Once you return to Zuul, you should see the option to create an autohold – an admin-only option.