the_information_nexus/tech_docs/keycloak.md

Focusing on integrating Keycloak with Ansible for managing Identity and Access Management (IAM) simplifies the process and aligns with modern IAM practices. Keycloak is an open-source IAM solution providing single sign-on with Identity Brokering and Social Login, User Federation, Client Adapters, an Admin Console, and an Account Management Console.

This guide assumes you have a basic understanding of IAM principles, Ansible, and Keycloak. We’ll cover setting up a Keycloak server using Ansible, configuring realms, clients, and users, and managing Keycloak configurations.

Environment Setup

• Control Machine: A Linux-based system with Ansible installed. This machine executes Ansible playbooks against target servers.
• Target Server: A Linux server (e.g., Ubuntu 20.04) designated to host Keycloak. Ensure it has Java (OpenJDK 11) installed, as Keycloak runs on the Java platform.

Step 1: Installing Ansible

1. On your control machine, ensure you have Ansible installed. You can install Ansible using your distribution's package manager. For example, on Ubuntu:

   sudo apt update
   sudo apt install ansible -y
   

2. Verify the installation by running ansible --version.

Step 2: Preparing Ansible Inventory

1. Create an inventory file named hosts in your working directory, and add the target server under a group [keycloak_servers]:

   [keycloak_servers]
   keycloak_server ansible_host=<TARGET_IP_ADDRESS> ansible_user=<SSH_USER>
   

2. Replace <TARGET_IP_ADDRESS> and <SSH_USER> with the target server's IP address and the SSH user, respectively.

Step 3: Keycloak Installation Playbook

1. Create a playbook named install_keycloak.yml. This playbook will handle the installation of Keycloak on the target server.

2. Playbook content:

   ---
   - name: Install and Configure Keycloak
     hosts: keycloak_servers
     become: yes
   
     tasks:
       - name: Download Keycloak
         get_url:
           url: https://github.com/keycloak/keycloak/releases/download/15.0.2/keycloak-15.0.2.tar.gz
           dest: /tmp/keycloak.tar.gz
   
       - name: Extract Keycloak Archive
         unarchive:
           src: /tmp/keycloak.tar.gz
           dest: /opt/
           remote_src: yes
   
       - name: Rename Keycloak Directory
         command: mv /opt/keycloak-15.0.2 /opt/keycloak
   
       - name: Update Permissions
         file:
           path: /opt/keycloak
           owner: keycloak
           group: keycloak
           recurse: yes
   
       - name: Install Keycloak as a Service
         template:
           src: keycloak.service.j2
           dest: /etc/systemd/system/keycloak.service
         notify: Restart Keycloak
   
       - name: Start Keycloak Service
         systemd:
           name: keycloak
           state: started
           enabled: yes
   
     handlers:
       - name: Restart Keycloak
         systemd:
           name: keycloak
           state: restarted
           enabled: yes
   

3. Create a systemd service template for Keycloak (keycloak.service.j2) in your Ansible working directory:

   [Unit]
   Description=Keycloak
   After=network.target
   
   [Service]
   User=keycloak
   PIDFile=/opt/keycloak/keycloak.pid
   ExecStart=/opt/keycloak/bin/standalone.sh -b 0.0.0.0
   SuccessExitStatus=143
   
   [Install]
   WantedBy=multi-user.target
   

4. Run the playbook to install Keycloak on the target server:

   ansible-playbook -i hosts install_keycloak.yml
   

Step 4: Configuring Keycloak with Ansible

After installing Keycloak, you'll likely want to manage realms, clients, users, and roles. Ansible doesn’t have built-in modules for Keycloak administration as of my last update. However, you can use the uri module to interact with Keycloak’s REST API for management tasks.

1. Create roles, users, and clients using Ansible tasks that make API calls to Keycloak. You’ll need to authenticate first to obtain an access token, then use that token for subsequent API requests.

2. API Authentication Example:

   - name: Authenticate with Keycloak
     uri:
       url: "http://<KEYCLOAK_IP>:8080/auth/realms/master/protocol/openid-connect/token"
       method: POST
       body: "client_id=admin-cli&username