# 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