digitalboard.core/roles/keycloak

Keycloak

Ansible role to deploy Keycloak with a PostgreSQL backend via Docker Compose, published behind Traefik. Optionally provisions realm resources (groups, users, OIDC clients, identity providers, LDAP user federations) through the community.general Keycloak modules.

Requirements

• Docker and Docker Compose on the target host (e.g. via digitalboard.core.base)
• Ansible collections: community.docker, and community.general when keycloak_provisioning_enabled is true
• Traefik reverse proxy with the proxy network already created (for external access)

Role variables

Key variables from defaults/main.yml:

Base configuration

Variable	Default	Description
docker_compose_base_dir	/etc/docker/compose	Base dir for Compose projects.
docker_volume_base_dir	/srv/data	Base dir for persistent volumes.
keycloak_service_name	keycloak	Compose/service name; builds the per-service paths.

Keycloak

Variable	Default	Description
keycloak_domain	keycloak.local.test	Host rule and KC_HOSTNAME.
keycloak_image	quay.io/keycloak/keycloak:24.0.1	Keycloak image.
keycloak_port	8080	Internal HTTP port advertised to Traefik.
keycloak_admin_user	admin	Bootstrap admin user.
keycloak_admin_password	changeme	Admin password — override this.
keycloak_log_level	INFO	KC_LOG_LEVEL.
keycloak_proxy_mode	edge	KC_PROXY mode.
keycloak_gzip_enabled	false	Toggle Keycloak GZIP response encoding.
keycloak_truststore_certificates	[]	Host PEM paths mounted into the truststore (KC_TRUSTSTORE_PATHS).
keycloak_extra_hosts	[]	Extra host:ip entries for the container.

PostgreSQL

Variable	Default	Description
keycloak_postgres_image	postgres:15	PostgreSQL image.
keycloak_postgres_db	keycloak	Database name.
keycloak_postgres_user	keycloak	Database user.
keycloak_postgres_password	changeme	Database password — override this.

Traefik

Variable	Default	Description
keycloak_traefik_network	proxy	External Traefik network.
keycloak_backend_network	backend	Internal network to PostgreSQL.
keycloak_use_ssl	true	Route on websecure with tls=true instead of web.

TLS is requested from Traefik via tls=true; the role does not set a certificate resolver, so Traefik issues/serves the certificate according to its own configuration.

Provisioning (optional)

Provisioning runs only when keycloak_provisioning_enabled is true. The tasks wait for the /health/ready endpoint and then call the community.general.keycloak_* modules, delegated to localhost against keycloak_auth_url (derived from keycloak_use_ssl + keycloak_domain).

Variable	Default	Description
keycloak_provisioning_enabled	false	Enable realm provisioning.
keycloak_realm	default	Target realm; created unless master.
keycloak_realm_display_name	Default Realm	Realm display name.
keycloak_auth_url	derived	API base URL for provisioning.
keycloak_groups	[]	Groups to create.
keycloak_local_users	[]	Local users to create.
keycloak_oidc_clients	[]	OIDC clients to create.
keycloak_identity_providers	[]	Identity providers (e.g. Entra ID).
keycloak_user_federations	[]	LDAP user federations.
keycloak_removed_users	[]	Usernames to delete.
keycloak_removed_groups	[]	Group names to delete.
keycloak_removed_clients	[]	Client IDs to delete.
keycloak_removed_identity_providers	[]	IdP aliases to delete.
keycloak_removed_user_federations	[]	Federation names to delete.

See defaults/main.yml for the full entry shape of each list.

Dependencies

This role requires the Traefik reverse proxy to be configured and the proxy network to be created beforehand (it is referenced as an external network in the Compose file). The backend network is created by the Compose project itself.

Example playbook

- hosts: backend_servers
  roles:
    - role: digitalboard.core.keycloak
      vars:
        keycloak_domain: "auth.example.com"
        keycloak_admin_password: "{{ vault_keycloak_admin_password }}"
        keycloak_postgres_password: "{{ vault_keycloak_pg_password }}"
        keycloak_provisioning_enabled: true
        keycloak_oidc_clients:
          - client_id: nextcloud
            name: "Nextcloud"
            client_secret: "{{ vault_nextcloud_client_secret }}"
            redirect_uris:
              - "https://nextcloud.example.com/apps/user_oidc/code"

License

MIT-0