Ansible Collection - redhat.sso

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

Ansible version compatibility

This collection has been tested against following Ansible versions: >=2.14.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 Automation Hub

Before using the collection, you need to setup Ansible Automation Hub as galaxy server; then install it via the CLI:

ansible-galaxy collection install redhat.sso

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: redhat.sso

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

• netaddr

A requirement file is provided to install:

pip install -r requirements.txt

Included roles

• sso: role for installing the service.
• sso_realm: role for configuring a realm, user federation(s), clients and users, in an installed service.
• sso_quarkus: role for installing the quarkus variant of keycloak (>= 17.0.0).

Usage

Install Playbook

• playbooks/sso.yml installs based on the defined variables (using most defaults).

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

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

Install from controller node (offline)

Making the sso zip archive available to the playbook working directory, and setting sso_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.

sso_offline_install: True

Downloading from the Customer Portal

The redhat.sso.sso role supports downloading and installing from the Red Hat Customer Portal using credentials associated to a service account. After login in the customer portal and navigating to the hybrid cloud console, select the services account tab to create one, if needed. Client ID and Client secret associated to the service account needs to be provided with the following variables are defined:

rhn_username: '<client_id>'
rhn_password: '<client_secret>'

The downloaded product archive will be stored in the controller working directory, and then distributed to target nodes.

When patching is requested, via the sso_apply_patches variable, the most recently published cumulative patch will be installed; to use a specific patch version instead, set it with the sso_patch_version variable.

NOTE: downgrading patches is not supported.

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

It is possible to perform downloads from alternate sources, using the sso_download_url variable; make sure the final downloaded filename matches with the source filename (ie. sso-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/sso.yml -e sso_admin_password=<changeme>

• sso_admin_password Password for the administration console user account.
• ansible_hosts is the inventory, below is an example inventory for deploying to localhost

[sso] 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/sso_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/sso_realm.yml -e sso_admin_password=<changeme> -e sso_realm=test

• sso_admin_password password for the administration console user account.
• sso_realm name of the realm to be created/used.
• ansible_hosts is the inventory, below is an example inventory for deploying to localhost

[sso] localhost ansible_connection=local

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

Support

redhat.sso collection v2.0.0 is for Technical Preview. If you have any issues or questions related to collection, please don't hesitate to contact us on Ansible-middleware-core@redhat.com or open an issue on https://github.com/ansible-middleware/keycloak/issues

License

Apache License v2.0 or later

See LICENSE to view the full text.