Ansible Collection - redhat.rhbk

Collection to install and configure Red Hat Build of Keycloak.

Ansible version compatibility

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

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.rhbk

The rhbk 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

• rhbk: role for installing the service.
• rhbk_realm: role for configuring a realm, user federation(s), clients and users, in an installed service.

Included modules

All Keycloak administration modules from community.general are provided in this collection for Keycloak 17+ (Quarkus). Use auth_rhbk_url without the legacy /auth context path (for example http://localhost:8080). Set rhbk_context to /auth only when automating WildFly-based Keycloak with the rhbk role.

• rhbk_authentication: manage authentication flows and executions using Keycloak Admin REST API.
• rhbk_authentication_flow: manage custom authentication flows and flow executions.
• rhbk_authentication_required_actions: manage required actions available in realm authentication.
• rhbk_authentication_v2: manage authentication flows with newer Keycloak API handling.
• rhbk_authz_authorization_scope: manage authorization scopes for a client resource server.
• rhbk_authz_custom_policy: manage custom authorization policies for a client resource server.
• rhbk_authz_permission: manage authorization permissions for a client resource server.
• rhbk_authz_permission_info: retrieve authorization permission information for a client resource server.
• rhbk_client: manage Keycloak clients (create/update/delete).
• rhbk_client_rolemapping: manage client role mappings for users and groups.
• rhbk_client_rolescope: manage client role scope mappings.
• rhbk_client_scope: manage client scopes and protocol mappers (replaces community.general.rhbk_clientscope).
• rhbk_client_scope_type: manage default and optional client scope assignments.
• rhbk_clientsecret_info: retrieve client secret information.
• rhbk_clientsecret_regenerate: regenerate a client secret.
• rhbk_clienttemplate: manage legacy client templates.
• rhbk_component: manage realm components.
• rhbk_component_info: retrieve realm component information.
• rhbk_group: manage realm groups and subgroups.
• rhbk_identity_provider: manage identity provider instances and configuration.
• rhbk_realm: manage realms (create/update/delete).
• rhbk_realm_info: retrieve realm information.
• rhbk_realm_key: manage realm key providers.
• rhbk_realm_keys_metadata_info: retrieve realm keys metadata.
• rhbk_realm_localization: manage realm localization texts.
• rhbk_realm_rolemapping: manage realm role mappings for users and groups.
• rhbk_role: manage realm and client roles.
• rhbk_user: manage users (create/update/delete).
• rhbk_user_execute_actions_email: trigger execute-actions emails for users.
• rhbk_user_federation: manage user federation providers (for example LDAP/AD).
• rhbk_user_rolemapping: manage user role mappings.
• rhbk_userprofile: manage user profile configuration.

Usage

The collection provides roles to install Keycloak and modules to manage realms, clients, users, and related settings via the Keycloak Admin REST API.

For Quarkus-based Keycloak (17+), set auth_rhbk_url to the server root URL without the legacy /auth path, for example http://localhost:8080. When using the legacy rhbk role with WildFly-based Keycloak, set rhbk_context to /auth in the rhbk_realm role.

Install Keycloak

• playbooks/rhbk.yml installs Keycloak >= 17 using the rhbk role.
• playbooks/rhbk.yml installs legacy Keycloak (<= 19) using the rhbk role.

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

Install from controller node (offline)

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

rhbk_offline_install: true

Downloading from the Customer Portal

The rhbk role supports downloading and installing from the Red Hat Customer Portal using credentials associated to a service account. After having authenticated in the customer portal, navigate to the hybrid cloud console, and select the services account tab to create one, if needed. Client ID and Client Secret associated to the service account need to be provided to the collection using the following variables:

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.

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

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

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

[rhbk] 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.

Configure with roles

The below example playbook can creates or updates provided realm, user federation(s), client(s), client role(s) and client user(s).

---
- name: Playbook for rhbk Hosts
  hosts: all
  vars:
    rhbk_admin_password: "remembertochangeme"
    rhbk_clients:
      - name: TestClient1
        client_id: TestClient1
        roles:
          - TestClient1Admin
          - TestClient1User
        realm: TestRealm
        public_client: true
        web_origins:
          - http://testclient1origin/application
          - http://testclient1origin/other
        users:
          - username: TestUser
            password: password
            client_roles:
              - client: TestClient1
                role: TestClient1User
                realm: TestRealm
  roles:
    - role: redhat.rhbk.rhbk_realm
      rhbk_realm: TestRealm

• playbooks/rhbk_realm_client.yml creates a realm with clients, roles and users using the rhbk_realm role.
• playbooks/rhbk_federation.yml configures user federation providers.

Example configuration command

Execute the following command from the source root directory:

ansible-playbook -i <ansible_hosts> playbooks/rhbk_realm.yml -e rhbk_realm_admin_password=<changeme> -e rhbk_realm_realm=test

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

[rhbk] localhost ansible_connection=local For full configuration details, refer to the rhbk_realm role.

Configure with modules

Module playbooks target an already running Keycloak instance. All modules use the redhat.rhbk collection namespace.

• playbooks/rhbk_client_scope.yml creates a client scope with protocol mappers using the rhbk_client_scope module.
• playbooks/rhbk_authentication_flow.yml creates a custom authentication flow with execution steps using the rhbk_authentication_flow module.

Example task using shared authentication defaults:

- hosts: localhost
  module_defaults:
    group/redhat.rhbk.rhbk:
      auth_rhbk_url: http://localhost:8080
      auth_realm: master
      auth_username: admin
      auth_password: "{{ rhbk_admin_password }}"
  tasks:
    - name: Create a user in a realm
      redhat.rhbk.rhbk_user:
        realm: TestRealm
        username: testuser
        first_name: Test
        last_name: User
        email: testuser@example.com
        enabled: true
        state: present

When migrating from community.general, replace the collection prefix in playbooks (for example community.general.rhbk_user becomes redhat.rhbk.rhbk_user) and use rhbk_client_scope instead of rhbk_clientscope.

Support

redhat.rhbk collection v3.0.2 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 referring to the keycloak_quarkus role

Release and Upgrade Notes

For details on changes between versions, please see the CHANGELOG for this collection.

License

Apache License v2.0 or later See LICENSE to view the full text.