Simple Ansible Keycloak Role Guide

What is This?

This Ansible role installs Keycloak on a system that uses systemd. It's meant for testing and development. Keycloak will be set up from a downloaded zip file.

It creates a system user named keycloak and a service to run Keycloak. The role also helps with some initial configurations, like setting ports, creating an admin user, and setting up TLS with self-signed or provided certificates. Firewall settings are also included.

How to Use It

Pick a playbook based on the TLS type you want:

• tls-self-signed.yml: Uses a self-signed certificate.
• tls-cert-key.yml: Uses an existing certificate/key file.
• tls-pkcs12.yml: Uses a PKCS12 bundle.

The playbooks use ansible-vault to secure sensitive information, using password as a placeholder for secrets. Replace these placeholders with your own secrets. Comments in the playbooks provide help on updating these values.

To run your playbook, use this command:

ansible-playbook --ask-vault-pass -i <inventory/host list> <playbook>

If Keycloak is already installed on the target system with the same version, the playbook won’t run to prevent data loss. If you want to overwrite it, set a variable called keycloak_force_install like this:

ansible-playbook ... --extra-vars "keycloak_force_install=yes"

Controlling Keycloak Archive Location

By default, the Keycloak archive downloads to the local system where you're running the playbook and is extracted there too. This saves some storage on the target, but can slow down the process if your upload speed is low.

Alternatively, you can choose to download straight to the target system by changing the keycloak_archive_on_target variable. This speeds up extraction since no data needs to be sent over the network, but the archive will stay on the target.

To control this when running your playbook, use:

-e "{keycloak_archive_on_target: True}"

Setting Up Variables

You can specify which Keycloak version to install:

• keycloak_version (default: 4.8.2.Final)

You'll need to provide the admin password, so specify this:

• keycloak_admin_password (keep it secure with ansible-vault)

You can set a different admin username with:

• keycloak_admin_user (default: admin)

To adjust network settings for Keycloak, use these:

• keycloak_bind_address (default: 0.0.0.0)
• keycloak_http_port (default: 8080)
• keycloak_https_port (default: 8443)

For PKCS12 TLS, specify:

• keycloak_tls_pkcs12 (path to the PKCS12 bundle)
• keycloak_tls_pkcs12_passphrase (keep it secure with ansible-vault)
• keycloak_tls_pkcs12_alias (name of the key/certificate)

For TLS using cert/key files, use:

• keycloak_tls_cert (path to the TLS certificate)
• keycloak_tls_key (path to the TLS key)

Note: The TLS files can be on your local machine or the remote target. By default, it assumes they're local. If they're on the target system, set keycloak_tls_files_on_target to True.

You can also set timeout values:

• keycloak_startup_timeout: Seconds to wait for Keycloak to start.
• keycloak_jboss_config_connect_timeout: Milliseconds for jboss to connect.
• keycloak_jboss_config_command_timeout: Seconds for jboss to complete commands.

Check roles/keycloak/defaults/main.yml for more variables to customize.

Testing

The role includes tests using Molecule with Docker. These tests check if everything works correctly. You can run them locally or in CI.

Role Name Note

Warning: The directory name must match the Ansible Galaxy role name.

To work properly, your cloned repo should have its directory name match the role name in molecule/default/playbook.yml.

Example:

$ cd ~/src
$ git clone [email protected]:nkinder/ansible-keycloak.git nkinder.keycloak
$ cd nkinder.keycloak

Run your tests with:

molecule test

You might want to add --debug to see more information:

molecule --debug test 2>&1 | tee molecule.log

Final Notes

You can choose different Docker images or versions to test against:

MOLECULE_DISTRO="fedora:28" molecule test

Future Improvements

• Add playbooks for setting up Keycloak with FreeIPA.
• Create playbooks for managing realms/clients with the Keycloak client module.
• Allow setting up IdM as a backend for Keycloak through SSSD.