This tutorial guides you through provisioning a Keycloak server using Ansible. Keycloak is an open-source identity and access management (IAM) solution perfect for securing your applications. Ansible is a powerful automation tool that simplifies server configuration and deployment.
Prerequisites:
- Ansible installed and configured on your control machine.
- An SSH connection established to the target server where you want to deploy Keycloak.
- Basic understanding of Ansible playbooks and roles. If you are new to Ansible playbooks, check this article: Ansible Playbook Example for beginners
Step 1: Install Keycloak Role
Ansible playbook and roles are available here: https://github.com/ansible-middleware/keycloak/tree/main
Download or clone the Repository on your machine. Then, we will install Keycloak Role.
Ansible Galaxy provides a pre-built role specifically designed for Keycloak provisioning. Use the following command to install it:
ansible-galaxy collection install middleware_automation.keycloak
Step 2: Create the Inventory File
An inventory file defines the target servers Ansible will manage. Create a file named hosts in your Ansible project directory and add the hostname or IP address of the server where you want to deploy Keycloak: For the sake of simplicity, we will install Keycloak on the same machine when you run Ansible.
Therefore, create the following hosts.ini Inventory file:
[keycloak] localhost ansible_connection=local
Step 3: Provision Keycloak
The playbooks folder of the Repository contains several Ansible playbooks you can use to provision a Keycloak installation. For example the playbooks/keycloak_quarkus_dev.yml will provision a Keycloak with Quarkus distribution that starts in dev mode:
---
- name: Playbook for Keycloak X Hosts in develop mode
hosts: all
vars:
keycloak_admin_password: "remembertochangeme"
keycloak_quarkus_host: localhost
keycloak_quarkus_port: 8080
keycloak_quarkus_log: file
keycloak_quarkus_start_dev: true
keycloak_quarkus_proxy_mode: none
roles:
- middleware_automation.keycloak.keycloak_quarkus
To learn more about running Keycloak Quarkus distribution check this article: Getting started with Keycloak powered by Quarkus
Then, provision Keycloak with the following command:
ansible-playbook -i hosts.ini playbooks/keycloak_quarkus_dev.yml -e keycloak_quarkus_admin_pass=francesco12345 --ask-become-pass
If you run an Ansible task that requires a privilege escalation, i.e. with become: true, you may get an error “sudo: a password is required”. Therefore we have added the --ask-become-pass which will prompt for the sudo password.
At the end of the Playbook installation, you should be able to find Keycloak in the following path:
sudo ls -ltr /opt/keycloak/keycloak-23.0.7 total 20 -rw-r--r--. 1 keycloak keycloak 26 Feb 22 08:39 version.txt -rw-r--r--. 1 keycloak keycloak 492 Feb 22 08:39 README.md -rw-r--r--. 1 keycloak keycloak 11358 Feb 22 08:39 LICENSE.txt drwxr-xr-x. 1 keycloak keycloak 56 Feb 22 08:58 lib drwxr-xr-x. 1 keycloak keycloak 18 Feb 22 08:58 themes drwxr-xr-x. 1 keycloak keycloak 18 Feb 22 08:58 providers drwxr-xr-x. 1 keycloak keycloak 150 Feb 22 08:58 bin drwxr-xr-x. 1 keycloak keycloak 108 Mar 26 12:38 conf drwxrwxr-x. 1 keycloak keycloak 10 Mar 26 12:38 data
Also, Keycloak is now running on localhost:8080:
How to customize Keycloak Playbook
The playbook in the repository uses defaults for most variables of the Role. You can fine-tune your Keycloak installation by setting the following Role attributes:
| Variable | Description | Default |
|---|---|---|
keycloak_admin_user | Administration console user account | admin |
keycloak_host | hostname | localhost |
keycloak_context | Context path for rest calls | /auth |
keycloak_http_port | HTTP port | 8080 |
keycloak_https_port | TLS HTTP port | 8443 |
keycloak_auth_realm | Name of the main authentication realm | master |
keycloak_management_http_port | Management port | 9990 |
keycloak_auth_client | Authentication client for configuration REST calls | admin-cli |
keycloak_client_public | Configure a public realm client | True |
keycloak_client_web_origins | Web origins for realm client | + |
keycloak_url | URL for configuration rest calls | http://{{ keycloak_host }}:{{ keycloak_http_port }} |
keycloak_management_url | URL for management console rest calls | http://{{ keycloak_host }}:{{ keycloak_management_http_port }} |
Conclusion
This article was a walkthough the provisioning of Keycloak with Ansible. By following these steps, you can leverage Ansible to automate Keycloak provisioning, reducing manual configuration tasks and streamlining your IAM infrastructure setup.
Found the article helpful? if so please follow us on Socials
