Update docs for 1.2.8

Signed-off-by: github-actions <ggraziol@redhat.com>
2025-07-28 07:31:30 -07:00 · 2023-08-28 15:59:12 +00:00 · 2023-08-28 15:59:12 +00:00 · 24c1210126
commit 24c1210126
parent 42b42df161
72 changed files with 20576 additions and 0 deletions
--- a/1.2.8/_sources/roles/index.rst.txt
+++ b/1.2.8/_sources/roles/index.rst.txt
@ -0,0 +1,7 @@
+Role Index
+==========
+
+.. toctree::
+    keycloak
+    keycloak_quarkus
+    keycloak_realm
--- a/1.2.8/_sources/roles/keycloak.md.txt
+++ b/1.2.8/_sources/roles/keycloak.md.txt
@ -0,0 +1,213 @@
+keycloak
+========
+
+Install [keycloak](https://keycloak.org/) or [Red Hat Single Sign-On](https://access.redhat.com/products/red-hat-single-sign-on) server configurations.
+
+
+Requirements
+------------
+
+This role requires the `python3-netaddr` library installed on the controller node.
+
+* to install via yum/dnf: `dnf install python3-netaddr`
+* or via pip: `pip install netaddr==0.8.0`
+* or via the collection: `pip install -r requirements.txt`
+
+
+Dependencies
+------------
+
+The roles depends on:
+
+* [middleware_automation.common](https://github.com/ansible-middleware/common)
+* [ansible-posix](https://docs.ansible.com/ansible/latest/collections/ansible/posix/index.html)
+
+To install all the dependencies via galaxy:
+
+    ansible-galaxy collection install -r requirements.yml
+
+
+Versions
+--------
+
+| RH-SSO VERSION | Release Date      | Keycloak Version | EAP Version | Notes           |
+|:---------------|:------------------|:-----------------|:------------|:----------------|
+|`7.5.0 GA`      |September 20, 2021 |`15.0.2`          | `7.4.6`     |[Release Notes](https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.5/html/release_notes/index)|
+|`7.6.0 GA`      |June 30, 2022      |`18.0.3`          | `7.4.6`     |[Release Notes](https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html-single/release_notes/index)|
+
+
+Patching
+--------
+
+When variable `keycloak_rhsso_apply_patches` is `True` (default: `False`), the role will automatically apply the latest cumulative patch for the selected base version.
+
+| RH-SSO VERSION | Release Date      | RH-SSO LATEST CP | Notes           |
+|:---------------|:------------------|:-----------------|:----------------|
+|`7.5.0 GA`      |January 20, 2022   |`7.5.3 GA`        |[Release Notes](https://access.redhat.com/articles/6646321)|
+|`7.6.0 GA`      |November 11, 2022  |`7.6.1 GA`        |[Release Notes](https://access.redhat.com/articles/6982711)|
+
+
+Role Defaults
+-------------
+
+* Service configuration
+
+| Variable | Description | Default |
+|:---------|:------------|:---------|
+|`keycloak_ha_enabled`| Enable auto configuration for database backend, clustering and remote caches on infinispan | `False` |
+|`keycloak_ha_discovery`| Discovery protocol for HA cluster members | `JDBC_PING` if keycloak_db_enabled else `TCPPING` |
+|`keycloak_db_enabled`| Enable auto configuration for database backend | `True` if `keycloak_ha_enabled` is True, else `False` |
+|`keycloak_remote_cache_enabled`| Enable remote cache store when in clustered ha configurations | `True` if `keycloak_ha_enabled` else `False` |
+|`keycloak_admin_user`| Administration console user account | `admin` |
+|`keycloak_bind_address`| Address for binding service ports | `0.0.0.0` |
+|`keycloak_management_port_bind_address`| Address for binding management ports | `127.0.0.1` |
+|`keycloak_host`| hostname | `localhost` |
+|`keycloak_http_port`| HTTP port | `8080` |
+|`keycloak_https_port`| TLS HTTP port | `8443` |
+|`keycloak_ajp_port`| AJP port | `8009` |
+|`keycloak_jgroups_port`| jgroups cluster tcp port | `7600` |
+|`keycloak_management_http_port`| Management port | `9990` |
+|`keycloak_management_https_port`| TLS management port | `9993` |
+|`keycloak_prefer_ipv4`| Prefer IPv4 stack and addresses for port binding | `True` |
+|`keycloak_config_standalone_xml`| filename for configuration | `keycloak.xml` |
+|`keycloak_service_user`| posix account username | `keycloak` |
+|`keycloak_service_group`| posix account group | `keycloak` |
+|`keycloak_service_restart_always`| systemd restart always behavior activation | `False`
+|`keycloak_service_restart_on_failure`| systemd restart on-failure behavior activation | `False`
+|`keycloak_service_startlimitintervalsec`| systemd StartLimitIntervalSec | `300` |
+|`keycloak_service_startlimitburst`| systemd StartLimitBurst | `5` |
+|`keycloak_service_restartsec`| systemd RestartSec | `10s` |
+|`keycloak_service_pidfile`| pid file path for service | `/run/keycloak.pid` |
+|`keycloak_features` | List of `name`/`status` pairs of features (also known as profiles on RH-SSO) to `enable` or `disable`, example: `[ { name: 'docker', status: 'enabled' } ]` | `[]`
+|`keycloak_jvm_package`| RHEL java package runtime | `java-1.8.0-openjdk-headless` |
+|`keycloak_java_home`| JAVA_HOME of installed JRE, leave empty for using specified keycloak_jvm_package RPM path | `None` |
+|`keycloak_java_opts`| Additional JVM options | `-Xms1024m -Xmx2048m` |
+
+
+* Install options
+
+| Variable | Description | Default |
+|:---------|:------------|:---------|
+|`keycloak_offline_install` | perform an offline install | `False`|
+|`keycloak_download_url`| Download URL for keycloak | `https://github.com/keycloak/keycloak/releases/download/<version>/<archive>`|
+|`keycloak_version`| keycloak.org package version | `18.0.2` |
+|`keycloak_dest`| Installation root path | `/opt/keycloak` |
+|`keycloak_download_url` | Download URL for keycloak | `https://github.com/keycloak/keycloak/releases/download/{{ keycloak_version }}/{{ keycloak_archive }}` |
+|`keycloak_configure_firewalld` | Ensure firewalld is running and configure keycloak ports | `False` |
+
+
+* Miscellaneous configuration
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+|`keycloak_archive` | keycloak install archive filename | `keycloak-legacy-{{ keycloak_version }}.zip` |
+|`keycloak_download_url_9x` | Download URL for keycloak (deprecated) | `https://downloads.jboss.org/keycloak/{{ keycloak_version }}/{{ keycloak_archive }}` |
+|`keycloak_installdir` | Installation path | `{{ keycloak_dest }}/keycloak-{{ keycloak_version }}` |
+|`keycloak_jboss_home` | Installation work directory | `{{ keycloak_rhsso_installdir }}` |
+|`keycloak_config_dir` | Path for configuration | `{{ keycloak_jboss_home }}/standalone/configuration` |
+|`keycloak_config_path_to_standalone_xml` | Custom path for configuration | `{{ keycloak_jboss_home }}/standalone/configuration/{{ keycloak_config_standalone_xml }}` |
+|`keycloak_config_override_template` | Path to custom template for standalone.xml configuration | `''` |
+|`keycloak_auth_realm` | Name for rest authentication realm | `master` |
+|`keycloak_auth_client` | Authentication client for configuration REST calls | `admin-cli` |
+|`keycloak_force_install` | Remove pre-existing versions of service | `False` |
+|`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 }}` |
+|`keycloak_frontend_url_force` | Force backend requests to use the frontend URL | `False` |
+|`keycloak_db_background_validation` | Enable background validation of database connection | `False` |
+|`keycloak_db_background_validation_millis`| How frequenly the connection pool is validated in the background | `10000` if background validation enabled |
+|`keycloak_db_background_validate_on_match` | Enable validate on match for database connections | `False` |
+|`keycloak_frontend_url` | frontend URL for keycloak endpoint | `http://localhost:8080/auth/` |
+
+
+
+Role Variables
+--------------
+
+The following are a set of _required_ variables for the role:
+
+| Variable | Description |
+|:---------|:------------|
+|`keycloak_admin_password`| Password for the administration console user account (minimum 12 characters) |
+|`keycloak_frontend_url` | frontend URL for keycloak endpoint | `http://localhost:8080/auth/` |
+
+
+The following parameters are _required_ only when `keycloak_ha_enabled` is True:
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+|`keycloak_modcluster_enabled`| Enable configuration for modcluster subsystem | `True` if `keycloak_ha_enabled` is True, else `False` |
+|`keycloak_modcluster_url` | _deprecated_ Host for the modcluster reverse proxy | `localhost` |
+|`keycloak_modcluster_port` | _deprecated_ Port for the modcluster reverse proxy | `6666` |
+|`keycloak_modcluster_urls` | List of {host,port} dicts for the modcluster reverse proxies | `[ { localhost:6666 } ]` |
+|`keycloak_jdbc_engine` | backend database engine when db is enabled: [ postgres, mariadb, sqlserver ] | `postgres` |
+|`keycloak_infinispan_url` | URL for the infinispan remote-cache server | `localhost:11122` |
+|`keycloak_infinispan_user` | username for connecting to infinispan | `supervisor` |
+|`keycloak_infinispan_pass` | password for connecting to infinispan | `supervisor` |
+|`keycloak_infinispan_sasl_mechanism`| Authentication type | `SCRAM-SHA-512` |
+|`keycloak_infinispan_use_ssl`| Enable hotrod TLS communication | `False` |
+|`keycloak_infinispan_trust_store_path`| Path to truststore with infinispan server certificate | `/etc/pki/java/cacerts` |
+|`keycloak_infinispan_trust_store_password`| Password for opening truststore | `changeit` |
+
+
+The following parameters are _required_ only when `keycloak_db_enabled` is True:
+
+| Variable | Description | Default |
+|:---------|:------------|:---------|
+|`keycloak_jdbc_url` | URL for the postgres backend database | `jdbc:postgresql://localhost:5432/keycloak` |
+|`keycloak_jdbc_driver_version`| Version for the JDBC driver to download | `9.4.1212` |
+|`keycloak_db_user` | username for connecting to postgres | `keycloak-user` |
+|`keycloak_db_pass` | password for connecting to postgres | `keycloak-pass` |
+
+
+The following variables are _optional_:
+
+| Variable | Description |
+|:---------|:------------|
+|`keycloak_db_valid_conn_sql` | Override the default database connection validation query sql |
+|`keycloak_admin_url` | Override the default administration endpoint URL |
+|`keycloak_jgroups_subnet`| Override the subnet match for jgroups cluster formation; if not defined, it will be inferred from local machine route configuration |
+
+Example Playbook
+-----------------
+
+* The following is an example playbook that makes use of the role to install keycloak from remote:
+
+```yaml
+---
+- hosts: ...
+      vars:
+        keycloak_admin_password: "remembertochangeme"
+      roles:
+        - middleware_automation.keycloak.keycloak
+```
+
+
+* The following example playbook makes use of the role to install keycloak from the controller node:
+
+```yaml
+---
+- hosts: ...
+      collections:
+        - middleware_automation.keycloak
+      tasks:
+        - name: Include keycloak role
+          include_role:
+            name: keycloak
+          vars:
+            keycloak_admin_password: "remembertochangeme"
+            keycloak_offline_install: True
+            # This should be the filename of keycloak archive on Ansible node: keycloak-16.1.0.zip
+```
+
+License
+-------
+
+Apache License 2.0
+
+
+Author Information
+------------------
+
+* [Guido Grazioli](https://github.com/guidograzioli)
+* [Romain Pelisse](https://github.com/rpelisse)
+* [Pavan Kumar Motaparthi](https://github.com/motaparthipavankumar)
--- a/1.2.8/_sources/roles/keycloak_quarkus.md.txt
+++ b/1.2.8/_sources/roles/keycloak_quarkus.md.txt
@ -0,0 +1,121 @@
+keycloak_quarkus
+================
+
+Install [keycloak](https://keycloak.org/) >= 20.0.0 (quarkus) server configurations.
+
+
+Role Defaults
+-------------
+
+* Installation options
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+|`keycloak_quarkus_version`| keycloak.org package version | `22.0.1` |
+
+
+* Service configuration
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+|`keycloak_quarkus_ha_enabled`| Enable auto configuration for database backend, clustering and remote caches on infinispan | `False` |
+|`keycloak_quarkus_db_enabled`| Enable auto configuration for database backend | `True` if `keycloak_quarkus_ha_enabled` is True, else `False` |
+|`keycloak_quarkus_admin_user`| Administration console user account | `admin` |
+|`keycloak_quarkus_bind_address`| Address for binding service ports | `0.0.0.0` |
+|`keycloak_quarkus_host`| hostname | `localhost` |
+|`keycloak_quarkus_http_port`| HTTP port | `8080` |
+|`keycloak_quarkus_https_port`| TLS HTTP port | `8443` |
+|`keycloak_quarkus_ajp_port`| AJP port | `8009` |
+|`keycloak_quarkus_jgroups_port`| jgroups cluster tcp port | `7600` |
+|`keycloak_quarkus_service_user`| Posix account username | `keycloak` |
+|`keycloak_quarkus_service_group`| Posix account group | `keycloak` |
+|`keycloak_quarkus_service_pidfile`| Pid file path for service | `/run/keycloak.pid` |
+|`keycloak_quarkus_jvm_package`| RHEL java package runtime | `java-17-openjdk-headless` |
+|`keycloak_quarkus_java_home`| JAVA_HOME of installed JRE, leave empty for using specified keycloak_quarkus_jvm_package RPM path | `None` |
+|`keycloak_quarkus_java_opts`| Additional JVM options | `-Xms1024m -Xmx2048m` |
+|`keycloak_quarkus_frontend_url`| Service public URL | `http://localhost:8080/auth` |
+|`keycloak_quarkus_http_relative_path` | Service context path | `auth` |
+|`keycloak_quarkus_http_enabled`| Enable listener on HTTP port | `True` |
+|`keycloak_quarkus_https_enabled`| Enable listener on HTTPS port | `False` |
+|`keycloak_quarkus_key_file`| The file path to a private key in PEM format | `{{ keycloak.home }}/conf/server.key.pem` |
+|`keycloak_quarkus_cert_file`| The file path to a server certificate or certificate chain in PEM format | `{{ keycloak.home }}/conf/server.crt.pem` |
+
+
+* Database configuration
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+|`keycloak_quarkus_jdbc_engine` | Database engine [mariadb,postres] | `postgres` |
+|`keycloak_quarkus_db_user` | User for database connection | `keycloak-user` |
+|`keycloak_quarkus_db_pass` | Password for database connection | `keycloak-pass` |
+|`keycloak_quarkus_jdbc_url` | JDBC URL for connecting to database | `jdbc:postgresql://localhost:5432/keycloak` |
+|`keycloak_quarkus_jdbc_driver_version` | Version for JDBC driver | `9.4.1212` |
+
+
+* Remote caches configuration
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+|`keycloak_quarkus_ispn_user` | Username for connecting to infinispan | `supervisor` |
+|`keycloak_quarkus_ispn_pass` | Password for connecting to infinispan | `supervisor` |
+|`keycloak_quarkus_ispn_url` | URL for connecting to infinispan | `localhost` |
+|`keycloak_quarkus_ispn_sasl_mechanism` | Infinispan auth mechanism | `SCRAM-SHA-512` |
+|`keycloak_quarkus_ispn_use_ssl` | Whether infinispan uses TLS connection | `false` |
+|`keycloak_quarkus_ispn_trust_store_path` | Path to infinispan server trust certificate | `/etc/pki/java/cacerts` |
+|`keycloak_quarkus_ispn_trust_store_password` | Password for infinispan certificate keystore | `changeit` | 
+
+
+* Install options
+
+| Variable | Description | Default |
+|:---------|:------------|:---------|
+|`keycloak_quarkus_offline_install` | Perform an offline install | `False`|
+|`keycloak_quarkus_download_url`| Download URL for keycloak | `https://github.com/keycloak/keycloak/releases/download/<version>/<archive>`| 
+|`keycloak_quarkus_version`| keycloak.org package version | `22.0.1` |
+|`keycloak_quarkus_dest`| Installation root path | `/opt/keycloak` |
+|`keycloak_quarkus_download_url` | Download URL for keycloak | `https://github.com/keycloak/keycloak/releases/download/{{ keycloak_quarkus_version }}/{{ keycloak_quarkus_archive }}` |
+|`keycloak_quarkus_configure_firewalld` | Ensure firewalld is running and configure keycloak ports | `False` |
+
+
+* Miscellaneous configuration
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+|`keycloak_quarkus_metrics_enabled`| Whether to enable metrics | `False` |
+|`keycloak_quarkus_health_enabled`| If the server should expose health check endpoints | `True` |
+|`keycloak_quarkus_archive` | keycloak install archive filename | `keycloak-{{ keycloak_quarkus_version }}.zip` |
+|`keycloak_quarkus_installdir` | Installation path | `{{ keycloak_quarkus_dest }}/keycloak-{{ keycloak_quarkus_version }}` |
+|`keycloak_quarkus_home` | Installation work directory | `{{ keycloak_quarkus_installdir }}` |
+|`keycloak_quarkus_config_dir` | Path for configuration | `{{ keycloak_quarkus_home }}/conf` |
+|`keycloak_quarkus_master_realm` | Name for rest authentication realm | `master` |
+|`keycloak_auth_client` | Authentication client for configuration REST calls | `admin-cli` |
+|`keycloak_force_install` | Remove pre-existing versions of service | `False` |
+|`keycloak_url` | URL for configuration rest calls | `http://{{ keycloak_quarkus_host }}:{{ keycloak_http_port }}` |
+|`keycloak_management_url` | URL for management console rest calls | `http://{{ keycloak_quarkus_host }}:{{ keycloak_management_http_port }}` |
+|`keycloak_quarkus_log`| Enable one or more log handlers in a comma-separated list | `file` |
+|`keycloak_quarkus_log_level`| The log level of the root category or a comma-separated list of individual categories and their levels | `info` |
+|`keycloak_quarkus_log_file`| Set the log file path and filename relative to keycloak home | `data/log/keycloak.log` |
+|`keycloak_quarkus_log_format`| Set a format specific to file log entries | `%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n` |
+|`keycloak_quarkus_proxy_mode`| The proxy address forwarding mode if the server is behind a reverse proxy | `edge` |
+|`keycloak_quarkus_start_dev`| Whether to start the service in development mode (start-dev) | `False` |
+|`keycloak_quarkus_transaction_xa_enabled`| Whether to use XA transactions | `True` |
+
+
+Role Variables
+--------------
+
+| Variable | Description | Required |
+|:---------|:------------|----------|
+|`keycloak_quarkus_admin_pass`| Password of console admin account | `yes` |
+
+
+License
+-------
+
+Apache License 2.0
+
+
+Author Information
+------------------
+
+* [Guido Grazioli](https://github.com/guidograzioli)
--- a/1.2.8/_sources/roles/keycloak_realm.md.txt
+++ b/1.2.8/_sources/roles/keycloak_realm.md.txt
@ -0,0 +1,139 @@
+keycloak_realm
+==============
+
+Create realms and clients in [keycloak](https://keycloak.org/) or [Red Hat Single Sign-On](https://access.redhat.com/products/red-hat-single-sign-on) services.
+
+
+Role Defaults
+-------------
+
+| 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 }}` |
+
+
+Role Variables
+--------------
+
+The following are a set of _required_ variables for the role:
+
+| Variable | Description |
+|:---------|:------------|
+|`keycloak_realm` | Name of the realm to be created |
+|`keycloak_admin_password`| Password for the administration console user account |
+
+
+The following variables are available for creating clients:
+
+| Variable | Description | Default |
+|:---------|:------------|:---------|
+|`keycloak_clients` | List of _client_ declarations for the realm | `[]` |
+|`keycloak_client_default_roles` | List of default role name for clients | `[]` |
+|`keycloak_client_users` | List of user/role mappings for a client | `[]` |
+
+
+The following variable are available for creating user federation:
+
+| Variable | Description | Default |
+|:---------|:------------|:---------|
+|`keycloak_user_federation` | List of _keycloak_user_federation_ for the realm | `[]` |
+
+
+Variable formats
+----------------
+
+* `keycloak_user_federation`, a list of:
+
+```yaml
+    - realm:  <name of the realm in which user federation should be configured, required>
+      name: <name of the user federation provider, required>
+      provider_id: <type of the user federation provider, required>
+      provider_type: <Provider Type, default is set to org.keycloak.storage.UserStorageProvider>
+      config: <dictionary of supported configuration values, required>
+      mappers: <list of supported configuration values, required>
+```
+
+Refer to [docs](https://docs.ansible.com/ansible/latest/collections/community/general/keycloak_user_federation_module.html) for information on supported variables.
+
+
+* `keycloak_clients`, a list of:
+
+```yaml
+    - name: <name of the client>
+      id: <id of the client>
+      client_id: <id of the client>
+      roles: <keycloak_client_default_roles>
+      realm: <name of the realm that contains the client>
+      public_client: <true for public, false for confidential>
+      web_origins: <list of allowed we origins for the client>
+      users: <keycloak_client_users>
+```
+
+`name` and either `id` or `client_id` are required.
+
+
+* `keycloak_client_users`, a list of:
+
+```yaml
+    - username: <username, required>
+      password: <password, required>
+      firstName: <firstName, optional>
+      lastName: <lastName, optional>
+      email: <email, optional>
+      client_roles: <list of client user/role mappings>
+```
+
+* Client user/role mappings, a list of:
+
+```yaml
+    - client: <name of the client>
+      role: <name of the role>
+      realm: <name of the realm>
+```
+
+For a comprehensive example, refer to the [playbook](../../playbooks/keycloak_realm.yml).
+
+
+Example Playbook
+----------------
+
+The following is an example playbook that makes use of the role to create a realm in keycloak.
+
+```yaml
+---
+- hosts: ...
+      collections:
+        - middleware_automation.keycloak
+      tasks:
+        - name: Include keycloak role
+          include_role:
+            name: keycloak_realm
+          vars:
+            keycloak_admin_password: "changeme"
+            keycloak_realm: TestRealm
+            keycloak_clients: [...]
+```
+
+
+License
+-------
+
+Apache License 2.0
+
+
+Author Information
+------------------
+
+* [Guido Grazioli](https://github.com/guidograzioli)
+* [Romain Pelisse](https://github.com/rpelisse)