Role Name

A role that installs the keycloak IdM https://keycloak.org

Role Variables

The most important variables are listed below:

keycloak_major_version: '19'
keycloak_minor_version: '0'
keycloak_point_version: '2'
keycloak_openjdk_runtime_version: 11
keycloak_openjdk_version:
  - '{{ keycloak_openjdk_runtime_version }}'
keycloak_openjdk_bin: '/usr/lib/jvm/java-{{ keycloak_openjdk_runtime_version}}-openjdk-amd64/bin/java'
keycloak_install_dir: '/opt/keycloak'
keycloak_distribution_data_directory: '{{ keycloak_install_dir }}/{{ keycloak_distribution }}/{{ keycloak_wildfly_mode }}'
keycloak_conf_directory: '{{ keycloak_runtime_home }}/conf'
keycloak_providers_directory: '{{ keycloak_runtime_home }}/providers'
keycloak_data_directory: '{{ keycloak_runtime_home }}/data'
keycloak_log_directory: '/var/log/keycloak'
keycloak_optimize_build_at_startup: true
keycloak_upgrade_db_at_startup: false
keycloak_disabled_features: []
keycloak_preview_features: []

keycloak_external_avatar_dir_enabled: false
keycloak_external_avatar_dir: '{{ keycloak_data_directory }}/avatar'

keycloak_https_enabled: true
keycloak_https_protocols: 'TLSv1.3'
keycloak_letsencrypt_certs: '{{ keycloak_https_enabled }}'
keycloak_http_enabled: "{% if keycloak_https_enabled %}'false'{% else %}'true'{% endif %}"
keycloak_listen: '127.0.0.1'
keycloak_http_port: 8080
keycloak_https_port: 8443
keycloak_set_hostname: false
keycloak_hostname: '{{ ansible_fqdn }}'

keycloak_log_handlers: console
keycloak_log_console_format: '%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n'
keycloak_log_console_output: default
keycloak_log_file: '{{ keycloak_log_directory }}/keycloak.log'
keycloak_log_file_format: '%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n'
keycloak_log_level: warning
# We keep those together because some health checks are available only when the metrics are enabled.
keycloak_metrics_and_health_checks_enabled: 'true'

keycloak_use_external_db: true
# postgresql is the only supported choice for the time being
keycloak_db_vendor: 'postgres'
keycloak_database_name: keycloak
keycloak_database_user: keycloak_u
# keycloak_database_password: 'define it into a vault file'
keycloak_database_host: 'localhost'
keycloak_database_max_pool_size: '50'
keycloak_database_jboss_connection_checker: true
keycloak_database_idle_timeouts_min: 1
keycloak_admin_user: kadmin
# keycloak_admin_password: 'define it into a vault file'

keycloak_before_nginx: false
keycloak_before_apache_httpd: false
keycloak_behind_reverse_proxy: true
keycloak_reverse_proxy_type: '{% if keycloak_local_certs %}reencrypt{% else %}edge{% endif %}'
keycloak_reverse_proxy_infinispan_attach_route: 'true'

keycloak_cluster: false
keycloak_cache_type: ispn
# jdbc-ping when Keycloak >= 26.2, tcp otherwise
keycloak_cache_stack: 'jdbc-ping'
keycloak_cache_container_name: keycloak

proxy_introspection_enabled: false
proxy_introspection_issuer: 'https://proxy.acc.myaccessid.org'
proxy_introspection_client_id: client-id-unconfigured
# proxy_introspection_client_secret: 'define it into a vault file'

Clustering (Infinispan/JGroups)

The role handles two different generations of the embedded Infinispan configuration, selected on keycloak_version.

Keycloak < 26.4: cache-ispn.xml carries the full list of cache definitions and, optionally, a custom JGroups stack; the bind address and the multicast address/port are passed as -Djgroups.* system properties by the systemd unit.

Keycloak >= 26.4: all cache definitions are created by Keycloak itself, so cache-ispn.xml only declares the cache container and the transport. Declaring the default caches there is deprecated (it logs a warning unless cache-config-mutate=true, and a future major release will refuse to start). Everything else is configured through options written in keycloak.conf:

Variable	Option in keycloak.conf	Notes
keycloak_cache_stack	cache-stack	jdbc-ping is the only non deprecated stack
keycloak_jgroups_bind_ip_address	cache-embedded-network-bind-address	written only if keycloak_jgroups_bind_specific_ip
keycloak_jgroups_bind_port	cache-embedded-network-bind-port	unicast data, default 7800
keycloak_jgroups_external_address	cache-embedded-network-external-address	only behind NAT
keycloak_jgroups_external_port	cache-embedded-network-external-port	only behind NAT
keycloak_cache_embedded_mtls_enabled	cache-embedded-mtls-enabled	default true, incompatible with UDP stacks
keycloak_cache_embedded_mtls_rotation_interval_days	cache-embedded-mtls-rotation-interval-days	default 30
keycloak_cache_embedded_max_counts	cache-embedded-<cache>-max-count	dict, kebab-case cache names
keycloak_cache_embedded_owners	spi-cache-embedded--default--<cache>-owners	dict, kebab-case cache names
keycloak_jgroups_fd_port_offset	-Djgroups.fd.port-offset	only has a system property

With the jdbc-ping stack there is no multicast traffic at all: the nodes register themselves in the JGROUPS_PING table of the Keycloak database and then communicate over TCP unicast only. The ports that must be reachable between the cluster members are:

Port	Protocol	Purpose
keycloak_jgroups_bind_port (7800)	TCP	JGroups unicast data transmission
bind port + keycloak_jgroups_fd_port_offset (57800)	TCP	FD_SOCK2 failure detection

Keep the sum of the two below 65535. Nothing else is needed: no UDP, no multicast group, no IGMP.

To move the cluster traffic to a dedicated network, set keycloak_jgroups_bind_specific_ip: true and point keycloak_jgroups_bind_ip_address at the address of the interface attached to that network. No change to cache-ispn.xml is required.

Dependencies

OpenJDK

License

EUPL-1.2

Author Information

Andrea Dell’Amico, andrea.dellamico@isti.cnr.it