# Ansible Collection - middleware_automation.keycloak

> NOTE: If you are Red Hat customer, install `redhat.rhbk` (for Red Hat Build of Keycloak) or `redhat.sso` (for Red Hat Single Sign-On) from Automation Hub as the certified version of this collection.

Collection to install and configure Keycloak or Red Hat Single Sign-On / Red Hat Build of Keycloak.

## Ansible version compatibility

This collection has been tested against following Ansible versions: >=2.15.0.

Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions.

## Installation

### Installing the Collection from Ansible Galaxy

Before using the collection, you need to install it with the Ansible Galaxy CLI:

    ansible-galaxy collection install middleware_automation.keycloak

You can also include it in a `requirements.yml` file and install it via `ansible-galaxy collection install -r requirements.yml`, using the format:

    ---
    collections:
      - name: middleware_automation.keycloak

The keycloak collection also depends on the following python packages to be present on the controller host:

- netaddr

- lxml

A requirement file is provided to install:

    pip install -r requirements.txt

### Included roles

- `keycloak_quarkus`: role for installing keycloak (>= 19.0.0, quarkus based).

- `keycloak_realm`: role for configuring a realm, user federation(s), clients and users, in an installed service.

- `keycloak`: role for installing legacy keycloak (<= 19.0, wildfly based).

## Usage

### Install Playbook

- `playbooks/keycloak_quarkus.yml` installs keycloak >= 17 based on the defined variables (using most defaults).

- `playbooks/keycloak.yml` installs keycloak legacy based on the defined variables (using most defaults).

Both playbooks include the `keycloak` role, with different settings, as described in the following sections.

For full service configuration details, refer to the keycloak role README.

#### Install from controller node (offline)

Making the keycloak zip archive available to the playbook working directory, and setting `keycloak_offline_install` to `true`, allows to skip the download tasks. The local path for the archive does match the downloaded archive path, so that it is also used as a cache when multiple hosts are provisioned in a cluster.

    keycloak_offline_install: true

#### Install from alternate sources (like corporate Nexus, artifactory, proxy, etc)

It is possible to perform downloads from alternate sources, using the `keycloak_download_url` variable; make sure the final downloaded filename matches with the source filename (ie. keycloak-legacy-x.y.zip or rh-sso-x.y.z-server-dist.zip).

### Example installation command

Execute the following command from the source root directory

    ansible-playbook -i <ansible_hosts> -e @rhn-creds.yml playbooks/keycloak.yml -e keycloak_admin_password=<changeme>

- `keycloak_admin_password` Password for the administration console user account.

- `ansible_hosts` is the inventory, below is an example inventory for deploying to localhost

      [keycloak]
      localhost ansible_connection=local

Note: when deploying clustered configurations, all hosts belonging to the cluster must be present in `ansible_play_batch`; ie. they must be targeted by the same ansible-playbook execution.

## Configuration

### Config Playbook

`playbooks/keycloak_realm.yml` creates or updates provided realm, user federation(s), client(s), client role(s) and client user(s).

### Example configuration command

Execute the following command from the source root directory:

    ansible-playbook -i <ansible_hosts> playbooks/keycloak_realm.yml -e keycloak_admin_password=<changeme> -e keycloak_realm=test

- `keycloak_admin_password` password for the administration console user account.

- `keycloak_realm` name of the realm to be created/used.

- `ansible_hosts` is the inventory, below is an example inventory for deploying to localhost

      [keycloak]
      localhost ansible_connection=local

For full configuration details, refer to the keycloak_realm role README.

## License

Apache License v2.0 or later

See LICENSE to view the full text.