03bf0efe44
Replace ansible-galaxy init placeholders across the collection and correct documentation that drifted from the code, after a multi-agent review of every role README against its defaults, tasks and templates. Collection level: - README: role table for all 16 roles, requirements and role-ordering - galaxy.yml: declare community.docker and community.general deps, real description/tags/urls; normalize license to MIT-0 - meta/runtime.yml: requires_ansible '>=2.15.0' - plugins/README: document the homarr_layout filter and garage_credentials lookup instead of scaffold boilerplate Per-role meta/main.yml and README for the placeholder roles (389ds, authentik, authentik_outpost_ldap, base, collabora, drawio, garage, homarr, httpbin, keycloak, nextcloud, opencloud, traefik). Correctness fixes found during review: - keycloak: wrong domain default, drop invented keycloak_cert_resolver, document the provisioning feature - garage: root_domain is .s3.<first-entry>, not the bare domain - opnform: jwt/front_api secrets use `openssl rand -hex 32`; align the validation fail_msg in tasks/main.yml accordingly - send: S3 example references garage_s3_domains[0] (was singular) - opencloud: document required opencloud_wopi_domain License normalized to MIT-0 across galaxy.yml, role meta and READMEs to match the SPDX headers.
119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
- 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
|