# keycloak_quarkus — Keycloak Ansible Collection documentation

# 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 rebuild config and restart the service after deploying, 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