middleware_automation.keycloak/roles/keycloak_quarkus/README.md

keycloak_quarkus

Install keycloak >= 20.0.0 (quarkus) server configurations.

Requirements

This role requires the python3-netaddr and lxml library installed on the controller node.

• to install via yum/dnf: dnf install python3-netaddr python3-lxml
• to install via apt: apt install python3-netaddr python3-lxml
• or via the collection: pip install -r requirements.txt

Dependencies

The roles depends on:

• middleware_automation.common
• ansible-posix

To install all the dependencies via galaxy:

ansible-galaxy collection install -r requirements.yml

Role Defaults

Installation options

Variable	Description	Default
keycloak_quarkus_version	keycloak.org package version	24.0.5
keycloak_quarkus_offline_install	Perform an offline install	False
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_download_path	Path local to controller for offline/download of install archives	{{ lookup('env', 'PWD') }}

Service configuration

Variable	Description	Default
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 for the Keycloak server	localhost
keycloak_quarkus_port	The port used by the proxy when exposing the hostname	-1
keycloak_quarkus_path	This should be set if proxy uses a different context-path for Keycloak
keycloak_quarkus_http_port	HTTP listening port	8080
keycloak_quarkus_https_port	TLS HTTP listening port	8443
keycloak_quarkus_ajp_port	AJP port	8009
keycloak_quarkus_service_user	Posix account username	keycloak
keycloak_quarkus_service_group	Posix account group	keycloak
keycloak_quarkus_service_restart_always	systemd restart always behavior activation	False
keycloak_quarkus_service_restart_on_failure	systemd restart on-failure behavior activation	False
keycloak_quarkus_service_restartsec	systemd RestartSec	10s
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_heap_opts	Heap memory JVM setting	-Xms1024m -Xmx2048m
keycloak_quarkus_java_jvm_opts	Other JVM settings	same as keycloak
keycloak_quarkus_java_opts	JVM arguments; if overridden, it takes precedence over keycloak_quarkus_java_*	{{ keycloak_quarkus_java_heap_opts + ' ' + keycloak_quarkus_java_jvm_opts }}
keycloak_quarkus_additional_env_vars	List of additional env variables of { key: str, value: str} to be put in sysconfig file	[]
keycloak_quarkus_frontend_url	Set the base URL for frontend URLs, including scheme, host, port and path
keycloak_quarkus_admin_url	Set the base URL for accessing the administration console, including scheme, host, port and path
keycloak_quarkus_http_relative_path	Set the path relative to / for serving resources. The path must start with a /	/
keycloak_quarkus_http_enabled	Enable listener on HTTP port	True
keycloak_quarkus_health_check_url_path	Path to the health check endpoint; scheme, host and keycloak_quarkus_http_relative_path will be prepended automatically	realms/master/.well-known/openid-configuration
keycloak_quarkus_https_key_file_enabled	Enable listener on HTTPS port	False
keycloak_quarkus_key_file_copy_enabled	Enable copy of key file to target host	False
keycloak_quarkus_key_content	Content of the TLS private key. Use "{{ lookup('file', 'server.key.pem') }}" to lookup a file.	""
keycloak_quarkus_key_file	The file path to a private key in PEM format	/etc/pki/tls/private/server.key.pem
keycloak_quarkus_cert_file_copy_enabled	Enable copy of cert file to target host	False
keycloak_quarkus_cert_file_src	Set the source file path	""
keycloak_quarkus_cert_file	The file path to a server certificate or certificate chain in PEM format	/etc/pki/tls/certs/server.crt.pem
keycloak_quarkus_https_key_store_enabled	Enable configuration of HTTPS via a key store	False
keycloak_quarkus_key_store_file	Deprecated, use keycloak_quarkus_https_key_store_file instead.
keycloak_quarkus_key_store_password	Deprecated, use keycloak_quarkus_https_key_store_password instead.
keycloak_quarkus_https_key_store_file	The file path to the key store	{{ keycloak.home }}/conf/key_store.p12
keycloak_quarkus_https_key_store_password	Password for the key store	""
keycloak_quarkus_https_trust_store_enabled	Enable configuration of the https trust store	False
keycloak_quarkus_https_trust_store_file	The file path to the trust store	{{ keycloak.home }}/conf/trust_store.p12
keycloak_quarkus_https_trust_store_password	Password for the trust store	""
keycloak_quarkus_proxy_headers	Parse reverse proxy headers (forwarded or xforwarded)	""
keycloak_quarkus_config_key_store_file	Path to the configuration key store; only used if keycloak_quarkus_keystore_password is not empty	{{ keycloak.home }}/conf/conf_store.p12 if keycloak_quarkus_keystore_password != '', else ''
keycloak_quarkus_config_key_store_password	Password of the configuration keystore; if non-empty, keycloak_quarkus_db_pass will be saved to the keystore at keycloak_quarkus_config_key_store_file instead of being written to the configuration file in clear text	""
keycloak_quarkus_configure_firewalld	Ensure firewalld is running and configure keycloak ports	False
keycloak_quarkus_configure_iptables	Ensure iptables is configured for keycloak ports	False

High-availability

Variable	Description	Default
keycloak_quarkus_ha_enabled	Enable auto configuration for database backend, clustering and remote caches on infinispan	False
keycloak_quarkus_ha_discovery	Discovery protocol for HA cluster members	TCPPING
keycloak_quarkus_db_enabled	Enable auto configuration for database backend	True if keycloak_quarkus_ha_enabled is True, else False
keycloak_quarkus_jgroups_port	jgroups cluster tcp port	7800
keycloak_quarkus_systemd_wait_for_port	Whether systemd unit should wait for keycloak port before returning	{{ keycloak_quarkus_ha_enabled }}
keycloak_quarkus_systemd_wait_for_port_number	Which port the systemd unit should wait for	{{ keycloak_quarkus_https_port }}
keycloak_quarkus_systemd_wait_for_log	Whether systemd unit should wait for service to be up in logs	false
keycloak_quarkus_systemd_wait_for_timeout	How long to wait for service to be alive (seconds)	60
keycloak_quarkus_systemd_wait_for_delay	Activation delay for service systemd unit (seconds)	10
keycloak_quarkus_restart_strategy	Strategy task file for restarting in HA (one of provided restart/['serial.yml','none.yml','serial_then_parallel.yml']) or path to file when providing custom strategy	restart/serial.yml
keycloak_quarkus_restart_health_check	Whether to wait for successful health check after restart	true
keycloak_quarkus_restart_health_check_delay	Seconds to let pass before starting healch checks	10
keycloak_quarkus_restart_health_check_reries	Number of attempts for successful health check before failing	25
keycloak_quarkus_restart_pause	Seconds to wait between restarts in HA strategy	15

Hostname configuration

Variable	Description	Default
keycloak_quarkus_http_relative_path	Set the path relative to / for serving resources. The path must start with a /	/
keycloak_quarkus_hostname_strict	Disables dynamically resolving the hostname from request headers	true
keycloak_quarkus_hostname_strict_backchannel	By default backchannel URLs are dynamically resolved from request headers to allow internal and external applications. If all applications use the public URL this option should be enabled.	false

Database configuration

Variable	Description	Default
keycloak_quarkus_jdbc_engine	Database engine [mariadb,postres,mssql]	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_hosts	host name/port for connecting to infinispan, eg. host1:11222;host2:11222	localhost:11222
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

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_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_log_target	Set the destination of the keycloak log folder link	/var/log/keycloak
keycloak_quarkus_log_max_file_size	Set the maximum log file size before a log rotation happens; A size configuration option recognises string in this format (shown as a regular expression): [0-9]+[KkMmGgTtPpEeZzYy]?. If no suffix is given, assume bytes.	10M
keycloak_quarkus_log_max_backup_index	Set the maximum number of archived log files to keep"	10
keycloak_quarkus_log_file_suffix	Set the log file handler rotation file suffix. When used, the file will be rotated based on its suffix; Note: If the suffix ends with .zip or .gz, the rotation file will also be compressed.	.yyyy-MM-dd.zip
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
keycloak_quarkus_spi_sticky_session_encoder_infinispan_should_attach_route	If the route should be attached to cookies to reflect the node that owns a particular session. If false, route is not attached to cookies and we rely on the session affinity capabilities from reverse proxy	True
keycloak_quarkus_show_deprecation_warnings	Whether deprecation warnings should be shown	True

Vault SPI

Variable	Description	Default
keycloak_quarkus_ks_vault_enabled	Whether to enable the vault SPI	false
keycloak_quarkus_ks_vault_file	The keystore path for the vault SPI	{{ keycloak_quarkus_config_dir }}/keystore.p12
keycloak_quarkus_ks_vault_type	Type of the keystore used for the vault SPI	PKCS12

Configuring providers

Variable	Description	Default
keycloak_quarkus_providers	List of provider definitions; see below	[]

Providers support different sources:

• url: http download for providers not requiring authentication
• maven: maven download for providers hosted publicly on Apache Maven Central or private Maven repositories like Github Maven requiring authentication
• local_path: static providers to be uploaded

Provider definition:

keycloak_quarkus_providers:
  - id: http-client                         # required; "{{ id }}.jar" identifies the file name on RHBK
    spi: connections                        # required if neither url, local_path nor maven are specified; required for setting properties
    default: true                           # optional, whether to set default for spi, default false
    restart: true                           # optional, whether to restart, default true
    url: https://.../.../custom_spi.jar     # optional, url for download via http
    local_path: my_theme_spi.jar            # optional, path on local controller for SPI to be uploaded
    maven:                                  # optional, for download using maven
      repository_url: https://maven.pkg.github.com/OWNER/REPOSITORY # optional, maven repo url
      group_id:  my.group                   # optional, maven group id
      artifact_id: artifact                 # optional, maven artifact id
      version: 24.0.5                       # optional, defaults to latest
      username:  user                       # optional, cf. https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-apache-maven-registry#authenticating-to-github-packages
      password: pat                         # optional, provide a PAT for accessing Github's Apache Maven registry
    properties:                             # optional, list of key-values
      - key: default-connection-pool-size
        value: 10

the definition above will generate the following build command:

bin/kc.sh build --spi-connections-provider=http-client --spi-connections-http-client-default-connection-pool-size=10

Configuring policies

Variable	Description	Default
keycloak_quarkus_policies	List of policy definitions; see below	[]

Provider definition:

keycloak_quarkus_policies:
  - name: xato-net-10-million-passwords.txt                                                                # required, resulting file name
    url: https://github.com/danielmiessler/SecLists/raw/master/Passwords/xato-net-10-million-passwords.txt # required, url for download
    type: password-blacklists                                                                              # optional, defaults to `password-blacklists`; supported values: [`password-blacklists`]

Role Variables

Variable	Description	Required
keycloak_quarkus_admin_pass	Password of console admin account	yes
keycloak_quarkus_frontend_url	Base URL for frontend URLs, including scheme, host, port and path	no
keycloak_quarkus_admin_url	Base URL for accessing the administration console, including scheme, host, port and path	no
keycloak_quarkus_ks_vault_pass	The password for accessing the keystore vault SPI	no
keycloak_quarkus_alternate_download_url	Alternate location with optional authentication for downloading RHBK	no
keycloak_quarkus_download_user	Optional username for http authentication	no*
keycloak_quarkus_download_pass	Optional password for http authentication	no*
keycloak_quarkus_download_validate_certs	Whether to validate certs for URL keycloak_quarkus_alternate_download_url	no
keycloak_quarkus_jdbc_download_user	Optional username for http authentication	no*
keycloak_quarkus_jdbc_download_pass	Optional password for http authentication	no*
keycloak_quarkus_jdbc_download_validate_certs	Whether to validate certs for URL keycloak_quarkus_download_validate_certs	no

* username/password authentication credentials must be both declared or both undefined

Role custom facts

The role uses the following custom facts found in /etc/ansible/facts.d/keycloak.fact (and thus identified by the ansible_local.keycloak. prefix):

Variable	Description
general.bootstrapped	A custom fact indicating whether this role has been used for bootstrapping keycloak on the respective host before; set to false (e.g., when starting off with a new, empty database) ensures that the initial admin user as defined by keycloak_quarkus_admin_user[_pass] gets created

License

Apache License 2.0

Author Information

• Guido Grazioli