This commit is contained in:
Madzone
2026-09-08 17:05:36 +02:00
parent d4ea6e5417
commit a6a3e72659
19 changed files with 760 additions and 0 deletions
+11
View File
@@ -0,0 +1,11 @@
group_vars/all.yml
group_vars/vault.yml
files/*.crt
*.retry
.venv/
# Lokale macOS-Dateien und Vault-Passwortdateien
.DS_Store
.vault-pass*
.vault_pass*
vault-password*
+14
View File
@@ -0,0 +1,14 @@
# Änderungsprotokoll
## [1.0.0] – 2026-09-08
Erste Version des Ansible-Setups für PVE 9 und Keycloak OIDC.
- Inventory für ts01 und die Keycloak-VM sowie konfigurierbare Realm- und Client-Werte.
- HEIMLAN_RootCA im Betriebssystem-, Java- und Keycloak-Truststore.
- OIDC-Realm, Rollengruppen, Gruppenmapper und variable Session-Zeiten.
- Idempotentes ACL-Mapping ausschließlich für existierende PVE-Gruppen.
- Secrets über Vault/Variablen; lokale Konfiguration und Zertifikate von Git ausgeschlossen.
- README und Dokumentation der lokalen Syntax- und ACL-Prüfungen.
Ein Integrationstest auf den Zielhosts steht aus.
+145
View File
@@ -0,0 +1,145 @@
# PVE 9 + Keycloak OIDC für HEIMLAN
Version: **1.0.0** · [Änderungsprotokoll](CHANGELOG.md) · [Versionsdatei](VERSION)
Dieses Ansible-Setup konfiguriert den bestehenden PVE-Host **ts01** und eine bestehende **Keycloak-VM**. Es installiert die private Root-CA auf beiden Betriebssystemen sowie im Java- und Keycloak-Truststore, richtet Realm, Client, Gruppen, Mapper und Sessions ein und ergänzt PVE-ACLs ausschließlich für bereits vorhandene Gruppen. Alle Module gehören zu `ansible.builtin`.
## Voraussetzungen und Umfang
- Ansible-Core 2.18/2.19 auf einem Controller mit passender Python-Version (für 2.19 Python ≥3.11); Python 3 auf beiden Zielhosts, SSH und root/sudo-Zugriff.
- PVE 9 ist installiert. Die Keycloak-VM läuft auf Debian/Ubuntu, mit einer bestehenden modernen Keycloak-Distribution (26.x, Quarkus), JVM und einem systemd-Dienst `keycloak`. Datenbank, VM-Erstellung, Keycloak-Binärinstallation und initialer Admin-Bootstrap sind Voraussetzung.
- Keycloak bietet **direkt HTTPS auf Port 8443**, ohne Reverse Proxy. Serverzertifikat mit SAN `keycloak.service.heim.lan`, privater Serverschlüssel und vollständige Intermediate-Kette müssen bereits konfiguriert sein. Der Import einer Root-CA stellt kein Serverzertifikat aus.
- DNS, Zeitabgleich und Erreichbarkeit müssen auf PVE, Keycloak und im Browser stimmen. Auch der Browser muss HEIMLAN_RootCA vertrauen.
- Bestehender Keycloak-Admin im `master`-Realm, der Realms anlegen und Zielrealm, Clients und Gruppen verwalten darf. Die Anmeldung erfolgt über `admin-cli` mit Password Grant. Für einen Admin mit vorgeschriebenem interaktivem MFA ist dieses Verfahren ungeeignet; dafür einen passenden Automationszugang bereitstellen.
- JVM-Pfad und Truststore müssen zur **tatsächlich gestarteten JVM** passen. Ein Container oder ein über `javax.net.ssl.trustStore` abweichend konfigurierter Dienst braucht entsprechend angepasste Pfade; das Beispiel steuert eine native systemd-Installation.
## Dateien
```text
ansible.cfg
inventory/hosts.yml
group_vars/all.yml.example
files/README.md
playbook/site.yml # vollständige Konfiguration
playbook/acl.yml # spätere ACL-Zuordnung nach Login
tasks/{preflight,ca,java,keycloak,keycloak_group,keycloak_mapper,pve,acl}.yml
```
## Einrichtung und Start
Alle Befehle im entpackten Verzeichnis ausführen:
```bash
python3 -m venv .venv
. .venv/bin/activate
pip install 'ansible-core>=2.18,<2.20'
cp group_vars/all.yml.example group_vars/all.yml
ansible-vault create group_vars/vault.yml
```
Im Vault-Editor die folgenden Variablen mit echten Werten anlegen. Die leeren Werte hier sind ausschließlich eine Vorlage; das Playbook lehnt sie ab:
```yaml
vault_keycloak_admin_username: ""
vault_keycloak_admin_password: ""
vault_keycloak_client_secret: ""
vault_java_cacerts_password: ""
```
Für das Client-Secret einen zufälligen Wert mit mindestens 16, maximal 256 Zeichen ohne führende/abschließende Leerzeichen oder Zeilenumbrüche verwenden. Das Java-Passwort muss das bestehende Truststore-Passwort sein; es wird nicht geändert. Keine Zugangsdaten im Inventory oder in der Kommandozeile eintragen.
1. `inventory/hosts.yml` anpassen: `ts01`, Keycloak-Adresse, SSH-Benutzer.
2. Öffentliche PEM-Root-CA als `files/HEIMLAN_RootCA.crt` ablegen, genau ein Zertifikat und **kein privater CA-Schlüssel**. Optional `heimlan_ca_sha256` auf einen unabhängig geprüften SHA-256-Fingerprint setzen, nur den Hexwert mit Doppelpunkten.
3. `group_vars/all.yml` prüfen: URL, Java-/Keycloak-Pfade, Servicebenutzer und tatsächliche Browser-URLs unter `pve_redirect_uris`. Beispiel: `https://ts01.heim.lan:8006/`. Für `https://ts01:8006/` einen eigenen Eintrag ergänzen. Keine Wildcards.
4. Bei abweichendem Issuer `keycloak_base_url`, `keycloak_realm` und ggf. `pve_oidc_issuer` konsistent ändern. Die Discovery-Antwort muss den Issuer exakt bestätigen. `pve_realm` bestimmt PVE-Benutzersuffix und PVE-Gruppensuffix.
5. SSH-Hostschlüssel vorab prüfen und in `known_hosts` aufnehmen.
```bash
ansible-playbook playbook/site.yml --syntax-check --ask-vault-pass
ansible-playbook playbook/site.yml --ask-vault-pass
```
Bei sudo-Passwort zusätzlich `--ask-become-pass`. Den vollständigen Lauf nicht mit `--limit pve` oder `--limit keycloak` zerlegen: CA-Fakten und Java-Prüfungen bauen aufeinander auf. `--check` wird für `site.yml` bewusst abgelehnt, da noch nicht angelegte API-Ressourcen und Truststores keinen verlässlichen Gesamtdryrun erlauben.
## Konfigurierte Werte
| Objekt | Einstellung |
|---|---|
| Keycloak-Realm | `main.heim.lan` |
| Client | `PVE-SERVER`, confidential, Authorization Code Flow |
| Issuer | `https://keycloak.service.heim.lan:8443/realms/main.heim.lan` |
| PVE-Realm | `main.heim.lan`, Typ `openid` |
| PVE-Optionen | `autocreate=1`, `groups-claim=groups`, `groups-autocreate=1`, `groups-overwrite=1`, `query-userinfo=1`, `username-claim=preferred_username` |
| Gruppenmapper | Name/Claim `groups`, Group Membership, Full group path **off**, ID/access/userinfo **on** |
| Username-Mapper | `pve-preferred-username`: Benutzerattribut `username` → `preferred_username`, ID/access/userinfo on |
| SSO Idle / Max | 900 / 28800 Sekunden (15 Minuten / 8 Stunden) |
| Client Idle / Max | 900 / 28800 Sekunden, Realm-Defaults und explizite Client-Overrides |
Keycloak erhält diese **Top-Level-Gruppen**, keine Keycloak-Rollen:
`Administrator`, `PVEAdmin`, `PVEAuditor`, `PVEDatastoreAdmin`, `PVEDatastoreUser`, `PVEMappingAdmin`, `PVEMappingUser`, `PVEPoolAdmin`, `PVEPoolUser`, `PVESDNAdmin`, `PVESDNUser`, `PVESysAdmin`, `PVETemplateUser`, `PVEUserAdmin`, `PVEVMAdmin`, `PVEVMUser`.
`NoAccess` wird nicht angelegt oder gemappt. Bestehende sonstige Gruppen und ACLs bleiben erhalten. Der Mapper liefert sämtliche Mitgliedschaften; für Rollen diese flachen Top-Level-Gruppen verwenden, damit gleichnamige Untergruppen bei ausgeschaltetem vollständigem Pfad nicht verwechselt werden.
## Erster Login und Rechte
1. In Keycloak einen vorhandenen Benutzer der gewünschten Gruppe zuweisen, beispielsweise `PVEAuditor` oder `PVEAdmin`. Benutzeranlage und Mitgliedschaften werden nicht automatisch verändert.
2. Im PVE-Login den Realm `main.heim.lan` auswählen und über Keycloak anmelden.
3. PVE erzeugt beim Login den Benutzer `BENUTZERNAME@main.heim.lan` und z. B. `PVEAuditor-main.heim.lan`. Bis zum ACL-Lauf kann der Benutzer noch ohne Rechte sein.
4. Anschließend ausführen:
```bash
ansible-playbook playbook/acl.yml
```
Dieser Lauf benötigt kein Vault und keinen Keycloak-API-Zugriff. Er vergibt für jede **bereits existierende** Gruppe `<ROLE>-main.heim.lan` die gleichnamige PVE-Rolle auf `/` mit `propagate=1`. Fehlende Gruppen werden gemeldet und übersprungen. Nach dem ersten Login weiterer Gruppen erneut ausführen. Eine bereits passende ACL erzeugt keine Änderung. Wie angefordert wirken die Rechte global auf `/` und werden vererbt.
## Bestehende Realms und Username-Migration
PVE kennzeichnet `username-claim` als **bei der Anlage festzulegen**. Das Playbook setzt den Wert bei der Neuanlage und übergibt ihn nicht bei `realm modify`. Ein vorhandener Realm mit fehlendem oder abweichendem Wert führt vor der PVE-Änderung zu einer verständlichen Fehlermeldung. Ein blindes `realm modify --username-claim ...` ist kein zuverlässiger Migrationsweg.
Für einen bereits mit UUID/`subject` eingerichteten Realm zuerst Benutzer, ACLs und lokale Notfallanmeldung sichern. Dann eine geplante Realm-Neuanlage oder einen neuen PVE-Realmnamen verwenden. Ein neuer Realmname ändert Benutzer- und Gruppensuffixe; alte UUID-Benutzer werden nicht automatisch mit neuen Benutzern zusammengeführt. Dieses Paket löscht dafür keine bestehenden Realms oder Benutzer. Keycloak kann in einem solchen abgebrochenen Gesamtlauf bereits aktualisiert sein; nach der Migration lässt sich der Lauf wiederholen.
## Idempotenz, TLS und Secrets
GET-Abfragen vergleichen die verwalteten Realm-/Client-/Mapper-Felder vor POST/PUT. Clientattribute außerhalb der verwalteten Sessionwerte werden erhalten. Die konfigurierte Redirect-Liste ist maßgeblich. Client-Secret wird über den dedizierten Keycloak-Endpunkt gelesen und mit dem Vault-Wert verglichen; PVE liest die lokale Realm-Konfiguration mit `pvesh`. Java-Alias wird anhand des Zertifikatfingerprints verglichen und bei CA-Wechsel ersetzt. OS-Trust-Aktualisierung läuft zur Reparierbarkeit jedes Mal, meldet bei unverändertem Store aber keine Änderung.
Jeder API-Aufruf verwendet CA- und Hostnamenprüfung. Die API-Tasks laufen **auf der Keycloak-VM**, die Discovery-Prüfung **auf PVE**; der Controller braucht deshalb für diese Aufrufe keinen eigenen CA-Import. Es gibt kein `validate_certs: false`, `curl -k` oder abgeschaltetes Hostname-Checking. Vertrauensänderungen starten den Keycloak-Dienst neu, bevor API-Aufrufe beginnen.
Alle Secrets kommen aus Variablen/Vault und sensitive Tasks nutzen `no_log`. PVE speichert seinen OIDC-Client-Key selbst in seiner Realm-Konfiguration; Vault verschlüsselt die Quelle, nicht den Laufzeitspeicher der Zielprodukte. Beim notwendigen `pveum`-Schreibaufruf ist der Key kurzzeitig ein Prozessargument auf PVE und damit für entsprechend privilegierte lokale Beobachter sichtbar. Keine Ansible-Debug-Ausgaben oder Prozessmitschnitte für diese Tasks aktivieren. Das Java-Passwort wird über eine Umgebungsvariable statt als Passwortargument übergeben.
Secret-Rotation: `ansible-vault edit group_vars/vault.yml`, denselben neuen Client-Key für den Gesamtlauf verwenden und `site.yml` erneut ausführen. Zwischen Keycloak- und PVE-Aktualisierung kann der Login kurzzeitig scheitern. Bestehende fremde ACLs werden nicht bereinigt; Entfernen einer Rolle aus `pve_roles` entzieht daher keine zuvor vergebenen Rechte.
## Session-Verhalten
Die Realm-SSO-Werte betreffen alle Anwendungen dieses Keycloak-Realms. Client-Overrides können die globale SSO-Grenze nicht verlängern. Kürzere Client-Sessions erzwingen bei weiterhin aktiver SSO-Session nicht zwangsläufig eine neue Passworteingabe.
Keycloak-Sessionablauf ist außerdem keine PVE-Ticket-Laufzeit: PVE-Aktivität muss Keycloak nicht aktiv halten und ein abgelaufener Keycloak-Login beendet nicht automatisch ein bereits ausgestelltes PVE-Ticket. Das Paket implementiert keinen Single-Logout-Patch; lokales PVE-Logout beendet die Keycloak-SSO-Session nicht automatisch.
## Prüfung und Fehlerdiagnose
Nach Konfiguration einen tatsächlichen Browser-Login durchführen. Im Keycloak-Client unter Client scopes → Evaluate für einen Testbenutzer kontrollieren, dass `groups` ein Array wie `["PVEAuditor"]` enthält, ohne führenden `/`, und `preferred_username` vorhanden ist. Vorhandene zusätzliche Mapper für dieselben Claims auf Widersprüche prüfen.
Auf PVE:
```bash
pveum group list --output-format json
pveum acl list --output-format json
pveum user list --output-format json
curl --fail --cacert /etc/ssl/certs/ca-certificates.crt \
https://keycloak.service.heim.lan:8443/realms/main.heim.lan/.well-known/openid-configuration
```
Bei TLS-Fehlern SAN, DNS, Systemzeit, CA-Datei und vom Server ausgelieferte Intermediate-Kette prüfen. Bei `invalid_redirect_uri` den tatsächlich im Browser verwendeten PVE-Origin einschließlich Port und abschließendem `/` eintragen. Bei versteckten API-Fehlern Keycloak-Serverlogs prüfen; `no_log` nicht pauschal abschalten. Bei fehlenden Rechten Gruppenmitgliedschaft, erneuten Login und ACL-Lauf prüfen. `groups-overwrite=1` ersetzt bestehende PVE-Gruppenmitgliedschaften dieses Benutzers beim Login.
Das Paket wird lokal auf YAML-/Ansible-Syntax und ausgewählte Entscheidungslogik geprüft. Ein Integrationstest auf deinem PVE/Keycloak sowie ein echter zweiter Lauf mit `changed=0` können ohne Zugriff auf deine Hosts nicht bestätigt werden.
## Referenzen
- [Proxmox OpenID-Dokumentation](https://github.com/proxmox/pve-docs/blob/master/pveum.adoc)
- [Proxmox OpenID-Plugin, insbesondere immutable username-claim](https://github.com/proxmox/pve-access-control/blob/master/src/PVE/Auth/OpenId.pm)
- [Proxmox ACL-API](https://github.com/proxmox/pve-access-control/blob/master/src/PVE/API2/ACL.pm)
- [Keycloak Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/index.html)
- [Keycloak Truststore](https://www.keycloak.org/server/keycloak-truststore)
- [Keycloak Session-Verwaltung](https://www.keycloak.org/docs/latest/server_admin/)
- [Keycloak Client-Session-Attributnamen](https://github.com/keycloak/keycloak/blob/main/server-spi-private/src/main/java/org/keycloak/protocol/oidc/OIDCConfigAttributes.java)
+11
View File
@@ -0,0 +1,11 @@
# Lokale Prüfung
Geprüft am 08.09.2026 mit Ansible-Core 2.19.12:
- Alle YAML-Dateien einschließlich Variablenbeispiel erfolgreich geparst.
- `site.yml` und `acl.yml`: Ansible-Syntaxprüfung erfolgreich.
- Vorbedingungen und zentrale PVE-/Keycloak-Variablenauswertung mit lokalen Testwerten erfolgreich; Client-Session-Attribute bleiben Strings, PVE-Flags sind Integer.
- Original-ACL-Tasks mit einem lokalen Ersatz für `pveum` ausgeführt: bestehende Gruppe ohne ACL erhält eine ACL; bestehende ACL mit `propagate=0` wird auf `1` korrigiert; fehlende Gruppe wird übersprungen.
- Zweiter ACL-Lauf gegen denselben Testzustand: `changed=0`, keine Fehler.
Keine Verbindung zu echten PVE-/Keycloak-Hosts wurde aufgebaut. TLS, Java-Keytool, Keycloak REST-Schreiboperationen, vollständige Idempotenz des Gesamtlaufs und Browser-Login müssen auf den Zielsystemen geprüft werden. Die lokale Prüfung ist kein Integrationstest.
+1
View File
@@ -0,0 +1 @@
1.0.0
+7
View File
@@ -0,0 +1,7 @@
[defaults]
inventory = inventory/hosts.yml
retry_files_enabled = False
host_key_checking = True
interpreter_python = auto_silent
[privilege_escalation]
become = True
+2
View File
@@ -0,0 +1,2 @@
Place the public, PEM-encoded HEIMLAN_RootCA certificate here as HEIMLAN_RootCA.crt.
Do not place the CA private key here. The certificate is not included in the archive.
+50
View File
@@ -0,0 +1,50 @@
# Copy to group_vars/all.yml. Paths are absolute on the managed host unless noted.
keycloak_base_url: https://keycloak.service.heim.lan:8443
keycloak_realm: main.heim.lan
pve_realm: main.heim.lan
keycloak_client_id: PVE-SERVER
pve_oidc_issuer: "{{ keycloak_base_url }}/realms/{{ keycloak_realm }}"
pve_redirect_uris:
- https://ts01.heim.lan:8006/
# Add each actual browser URL explicitly, e.g. https://ts01:8006/.
keycloak_admin_realm: master
keycloak_admin_client_id: admin-cli
keycloak_admin_username: "{{ vault_keycloak_admin_username }}"
keycloak_admin_password: "{{ vault_keycloak_admin_password }}"
keycloak_client_secret: "{{ vault_keycloak_client_secret }}"
# Seconds; realm values affect ALL applications in main.heim.lan.
keycloak_sso_idle: 900
keycloak_sso_max: 28800
keycloak_client_idle: 900
keycloak_client_max: 28800
# Public CA certificate on the Ansible controller, PEM, one certificate only.
heimlan_ca_src: "{{ playbook_dir }}/../files/HEIMLAN_RootCA.crt"
# Optional separately verified fingerprint, openssl x509 -fingerprint -sha256 format.
heimlan_ca_sha256: ""
system_ca_bundle: /etc/ssl/certs/ca-certificates.crt
keycloak_home: /opt/keycloak
keycloak_service: keycloak
keycloak_user: keycloak
keycloak_group: keycloak
# Must be the cacerts file of the JVM actually running Keycloak.
java_cacerts_path: /etc/ssl/certs/java/cacerts
java_keytool: /usr/bin/keytool
java_cacerts_password: "{{ vault_java_cacerts_password }}"
java_ca_alias: heimlan-rootca-ansible
pve_roles:
- Administrator
- PVEAdmin
- PVEAuditor
- PVEDatastoreAdmin
- PVEDatastoreUser
- PVEMappingAdmin
- PVEMappingUser
- PVEPoolAdmin
- PVEPoolUser
- PVESDNAdmin
- PVESDNUser
- PVESysAdmin
- PVETemplateUser
- PVEUserAdmin
- PVEVMAdmin
- PVEVMUser
+12
View File
@@ -0,0 +1,12 @@
all:
children:
pve:
hosts:
ts01:
ansible_host: ts01.heim.lan
ansible_user: root
keycloak:
hosts:
keycloak-vm:
ansible_host: keycloak.service.heim.lan
ansible_user: ansible
+9
View File
@@ -0,0 +1,9 @@
- name: Map only existing PVE groups after OIDC login
hosts: pve
become: true
serial: 1
gather_facts: false
vars_files:
- ../group_vars/all.yml
tasks:
- ansible.builtin.import_tasks: ../tasks/acl.yml
+35
View File
@@ -0,0 +1,35 @@
- name: Install private CA on both systems
hosts: pve:keycloak
become: true
vars_files:
- ../group_vars/all.yml
- ../group_vars/vault.yml
tasks:
- ansible.builtin.import_tasks: ../tasks/preflight.yml
- ansible.builtin.import_tasks: ../tasks/ca.yml
- name: Configure Keycloak trust and OIDC
hosts: keycloak
become: true
vars_files:
- ../group_vars/all.yml
- ../group_vars/vault.yml
tasks:
- ansible.builtin.import_tasks: ../tasks/java.yml
- ansible.builtin.import_tasks: ../tasks/keycloak.yml
handlers:
- name: Restart Keycloak
ansible.builtin.systemd_service:
name: "{{ keycloak_service }}"
state: restarted
- name: Configure PVE OpenID and existing group ACLs
hosts: pve
become: true
serial: 1
vars_files:
- ../group_vars/all.yml
- ../group_vars/vault.yml
tasks:
- ansible.builtin.import_tasks: ../tasks/pve.yml
- ansible.builtin.import_tasks: ../tasks/acl.yml
+33
View File
@@ -0,0 +1,33 @@
- name: Read existing PVE groups
ansible.builtin.command: pveum group list --output-format json
register: acl_groups
changed_when: false
check_mode: false
- name: Read existing PVE roles
ansible.builtin.command: pveum role list --output-format json
register: acl_roles
changed_when: false
check_mode: false
- name: Validate configured roles
ansible.builtin.assert:
that:
- "'NoAccess' not in pve_roles"
- pve_roles | difference(acl_roles.stdout | from_json | map(attribute='roleid') | list) | length == 0
- name: Read existing PVE ACLs
ansible.builtin.command: pveum acl list --output-format json
register: acl_current
changed_when: false
check_mode: false
- name: Map each existing group on root with propagation
ansible.builtin.command:
argv: [pveum, acl, modify, /, --groups, "{{ item }}-{{ pve_realm }}", --roles, "{{ item }}", --propagate, '1']
loop: "{{ pve_roles }}"
when:
- (item ~ '-' ~ pve_realm) in (acl_groups.stdout | from_json | map(attribute='groupid') | list)
- acl_current.stdout | from_json | selectattr('path', 'equalto', '/') | selectattr('type', 'equalto', 'group') | selectattr('ugid', 'equalto', item ~ '-' ~ pve_realm) | selectattr('roleid', 'equalto', item) | selectattr('propagate', 'equalto', 1) | list | length == 0
changed_when: true
- name: Show groups awaiting their first OIDC login
ansible.builtin.debug:
msg: "{{ item }}-{{ pve_realm }} does not exist yet; log in a member through OIDC, then run playbook/acl.yml."
loop: "{{ pve_roles }}"
when: (item ~ '-' ~ pve_realm) not in (acl_groups.stdout | from_json | map(attribute='groupid') | list)
+31
View File
@@ -0,0 +1,31 @@
- name: Install OS trust tools
ansible.builtin.apt:
name: [ca-certificates, openssl]
state: present
- name: Copy public root CA
ansible.builtin.copy:
src: "{{ heimlan_ca_src }}"
dest: /usr/local/share/ca-certificates/HEIMLAN_RootCA.crt
owner: root
group: root
mode: '0644'
register: ca_copy
- name: Check CA validity
ansible.builtin.command:
argv: [openssl, x509, -in, /usr/local/share/ca-certificates/HEIMLAN_RootCA.crt, -noout, -checkend, '0']
changed_when: false
- name: Read CA fingerprint
ansible.builtin.command:
argv: [openssl, x509, -in, /usr/local/share/ca-certificates/HEIMLAN_RootCA.crt, -noout, -fingerprint, -sha256]
register: ca_fingerprint
changed_when: false
- name: Verify expected fingerprint when supplied
ansible.builtin.assert:
that: ca_fingerprint.stdout.split('=')[-1] | lower == heimlan_ca_sha256 | lower
when: heimlan_ca_sha256 | length > 0
- name: Update system trust (also repairs an interrupted previous run)
ansible.builtin.command: update-ca-certificates
environment:
LC_ALL: C
register: ca_update
changed_when: "ca_copy.changed or '0 added, 0 removed' not in ca_update.stdout"
+67
View File
@@ -0,0 +1,67 @@
- name: Check actual Java truststore and Keycloak installation
ansible.builtin.stat:
path: "{{ item }}"
loop:
- "{{ java_cacerts_path }}"
- "{{ java_keytool }}"
- "{{ keycloak_home }}/bin/kc.sh"
register: java_paths
- name: Require installed JVM and Keycloak
ansible.builtin.assert:
that: item.stat.exists
fail_msg: 'Adjust Java/Keycloak paths to the existing installation.'
loop: "{{ java_paths.results }}"
loop_control:
label: "{{ item.item }}"
- name: Install CA in Keycloak system trust directory
ansible.builtin.file:
path: "{{ keycloak_home }}/conf/truststores"
state: directory
owner: "{{ keycloak_user }}"
group: "{{ keycloak_group }}"
mode: '0755'
- name: Copy CA for Keycloak truststore discovery
ansible.builtin.copy:
src: "{{ heimlan_ca_src }}"
dest: "{{ keycloak_home }}/conf/truststores/HEIMLAN_RootCA.pem"
owner: "{{ keycloak_user }}"
group: "{{ keycloak_group }}"
mode: '0644'
notify: Restart Keycloak
- name: Inspect existing managed Java CA alias
ansible.builtin.command:
argv: ["{{ java_keytool }}", -exportcert, -rfc, -alias, "{{ java_ca_alias }}", -keystore, "{{ java_cacerts_path }}", '-storepass:env', ANSIBLE_JAVA_STOREPASS]
environment:
ANSIBLE_JAVA_STOREPASS: "{{ java_cacerts_password }}"
LC_ALL: C
register: java_export
changed_when: false
failed_when: java_export.rc != 0 and 'does not exist' not in (java_export.stdout ~ java_export.stderr)
no_log: true
- name: Read existing Java CA fingerprint
ansible.builtin.command:
argv: [openssl, x509, -noout, -fingerprint, -sha256]
stdin: "{{ java_export.stdout }}"
register: java_fingerprint
changed_when: false
when: java_export.rc == 0
- name: Rotate managed Java CA alias if certificate changed
ansible.builtin.command:
argv: ["{{ java_keytool }}", -delete, -alias, "{{ java_ca_alias }}", -keystore, "{{ java_cacerts_path }}", '-storepass:env', ANSIBLE_JAVA_STOREPASS]
environment:
ANSIBLE_JAVA_STOREPASS: "{{ java_cacerts_password }}"
LC_ALL: C
when: java_export.rc == 0 and java_fingerprint.stdout != ca_fingerprint.stdout
no_log: true
notify: Restart Keycloak
- name: Import CA into the JVM used by Keycloak
ansible.builtin.command:
argv: ["{{ java_keytool }}", -importcert, -noprompt, -trustcacerts, -alias, "{{ java_ca_alias }}", -file, /usr/local/share/ca-certificates/HEIMLAN_RootCA.crt, -keystore, "{{ java_cacerts_path }}", '-storepass:env', ANSIBLE_JAVA_STOREPASS]
environment:
ANSIBLE_JAVA_STOREPASS: "{{ java_cacerts_password }}"
LC_ALL: C
when: java_export.rc != 0 or java_fingerprint.stdout | default('') != ca_fingerprint.stdout
no_log: true
notify: Restart Keycloak
- name: Apply trust before API access
ansible.builtin.meta: flush_handlers
+176
View File
@@ -0,0 +1,176 @@
- name: Configure Keycloak through verified HTTPS
no_log: true
module_defaults:
ansible.builtin.uri:
validate_certs: true
ca_path: "{{ system_ca_bundle }}"
use_proxy: false
follow_redirects: none
unredirected_headers: [Authorization]
timeout: 30
block:
- name: Obtain short-lived admin token
ansible.builtin.uri:
url: "{{ keycloak_base_url }}/realms/{{ keycloak_admin_realm }}/protocol/openid-connect/token"
method: POST
body_format: form-urlencoded
body:
grant_type: password
client_id: "{{ keycloak_admin_client_id }}"
username: "{{ keycloak_admin_username }}"
password: "{{ keycloak_admin_password }}"
status_code: 200
register: kc_token
until: kc_token.status | default(0) == 200
retries: 20
delay: 3
changed_when: false
- name: Define admin headers and realm settings
ansible.builtin.set_fact:
kc_headers:
Authorization: "Bearer {{ kc_token.json.access_token }}"
kc_api: "{{ keycloak_base_url }}/admin/realms/{{ keycloak_realm }}"
kc_realm_desired:
realm: "{{ keycloak_realm }}"
enabled: true
ssoSessionIdleTimeout: "{{ keycloak_sso_idle | int }}"
ssoSessionMaxLifespan: "{{ keycloak_sso_max | int }}"
clientSessionIdleTimeout: "{{ keycloak_client_idle | int }}"
clientSessionMaxLifespan: "{{ keycloak_client_max | int }}"
- name: Read realm
ansible.builtin.uri:
url: "{{ kc_api }}"
headers: "{{ kc_headers }}"
status_code: [200, 404]
register: kc_realm_current
- name: Create realm if missing
ansible.builtin.uri:
url: "{{ keycloak_base_url }}/admin/realms"
headers: "{{ kc_headers }}"
method: POST
body_format: json
body: "{{ kc_realm_desired }}"
status_code: 201
when: kc_realm_current.status == 404
changed_when: true
- name: Determine realm drift
ansible.builtin.set_fact:
kc_realm_drift: "{{ (kc_realm_current.json | default({}) | combine(kc_realm_desired)) != (kc_realm_current.json | default({})) }}"
- name: Update only managed realm fields
ansible.builtin.uri:
url: "{{ kc_api }}"
headers: "{{ kc_headers }}"
method: PUT
body_format: json
body: "{{ kc_realm_desired }}"
status_code: 204
when: kc_realm_current.status == 200 and kc_realm_drift
changed_when: true
- name: Ensure each top-level group exists
ansible.builtin.include_tasks: keycloak_group.yml
loop: "{{ pve_roles }}"
loop_control:
loop_var: kc_group_name
- name: Find client by exact ID
ansible.builtin.uri:
url: "{{ kc_api }}/clients?clientId={{ keycloak_client_id | urlencode }}"
headers: "{{ kc_headers }}"
register: kc_clients
- name: Select exact match
ansible.builtin.set_fact:
kc_matches: "{{ kc_clients.json | selectattr('clientId', 'equalto', keycloak_client_id) | list }}"
- name: Require unique client
ansible.builtin.assert:
that: kc_matches | length <= 1
- name: Define client settings
ansible.builtin.set_fact:
kc_client_desired:
clientId: "{{ keycloak_client_id }}"
protocol: openid-connect
enabled: true
publicClient: false
bearerOnly: false
clientAuthenticatorType: client-secret
standardFlowEnabled: true
implicitFlowEnabled: false
directAccessGrantsEnabled: false
serviceAccountsEnabled: false
redirectUris: "{{ pve_redirect_uris }}"
webOrigins: []
kc_session_attributes:
client.session.idle.timeout: "{{ keycloak_client_idle | string }}"
client.session.max.lifespan: "{{ keycloak_client_max | string }}"
- name: Create confidential PVE client
ansible.builtin.uri:
url: "{{ kc_api }}/clients"
headers: "{{ kc_headers }}"
method: POST
body_format: json
body: "{{ kc_client_desired | combine({'secret': keycloak_client_secret, 'attributes': kc_session_attributes, 'defaultClientScopes': ['profile', 'email']}) }}"
status_code: 201
when: kc_matches | length == 0
changed_when: true
- name: Read client after creation
ansible.builtin.uri:
url: "{{ kc_api }}/clients?clientId={{ keycloak_client_id | urlencode }}"
headers: "{{ kc_headers }}"
register: kc_clients
- name: Store client representation
ansible.builtin.set_fact:
kc_client_current: "{{ kc_clients.json | selectattr('clientId', 'equalto', keycloak_client_id) | first }}"
- name: Read actual client secret (not masked representation)
ansible.builtin.uri:
url: "{{ kc_api }}/clients/{{ kc_client_current.id }}/client-secret"
headers: "{{ kc_headers }}"
register: kc_secret
- name: Merge managed attributes preserving other client settings
ansible.builtin.set_fact:
kc_client_update: "{{ kc_client_desired | combine({'attributes': (kc_client_current.attributes | default({}) | combine(kc_session_attributes))}) }}"
- name: Update client only on drift or secret rotation
ansible.builtin.uri:
url: "{{ kc_api }}/clients/{{ kc_client_current.id }}"
headers: "{{ kc_headers }}"
method: PUT
body_format: json
body: "{{ kc_client_update | combine({'secret': keycloak_client_secret}) }}"
status_code: 204
when: (kc_client_current | combine(kc_client_update)) != kc_client_current or kc_secret.json.value != keycloak_client_secret
changed_when: true
- name: Ensure username claim independent of inherited client scopes
ansible.builtin.include_tasks: keycloak_mapper.yml
vars:
kc_mapper_desired:
name: pve-preferred-username
protocol: openid-connect
protocolMapper: oidc-usermodel-property-mapper
consentRequired: false
config:
user.attribute: username
claim.name: preferred_username
jsonType.label: String
id.token.claim: 'true'
access.token.claim: 'true'
userinfo.token.claim: 'true'
- name: Ensure flat group membership mapper
ansible.builtin.include_tasks: keycloak_mapper.yml
vars:
kc_mapper_desired:
name: groups
protocol: openid-connect
protocolMapper: oidc-group-membership-mapper
consentRequired: false
config:
claim.name: groups
full.path: 'false'
id.token.claim: 'true'
access.token.claim: 'true'
userinfo.token.claim: 'true'
always:
- name: Clear authentication facts
ansible.builtin.set_fact:
kc_headers: {}
kc_token: {}
kc_secret: {}
kc_client_current: {}
kc_clients: {}
kc_matches: []
+16
View File
@@ -0,0 +1,16 @@
- name: Find exact top-level Keycloak group
ansible.builtin.uri:
url: "{{ kc_api }}/groups?search={{ kc_group_name | urlencode }}&exact=true&first=0&max=100&briefRepresentation=true"
headers: "{{ kc_headers }}"
register: kc_group_search
- name: Create missing top-level Keycloak group
ansible.builtin.uri:
url: "{{ kc_api }}/groups"
headers: "{{ kc_headers }}"
method: POST
body_format: json
body:
name: "{{ kc_group_name }}"
status_code: 201
when: kc_group_search.json | selectattr('path', 'equalto', '/' ~ kc_group_name) | list | length == 0
changed_when: true
+33
View File
@@ -0,0 +1,33 @@
- name: Read client protocol mappers
ansible.builtin.uri:
url: "{{ kc_api }}/clients/{{ kc_client_current.id }}/protocol-mappers/models"
headers: "{{ kc_headers }}"
register: kc_mappers
- name: Select mapper by name
ansible.builtin.set_fact:
kc_mapper_matches: "{{ kc_mappers.json | selectattr('name', 'equalto', kc_mapper_desired.name) | list }}"
- name: Check mapper uniqueness
ansible.builtin.assert:
that: kc_mapper_matches | length <= 1
- name: Create mapper
ansible.builtin.uri:
url: "{{ kc_api }}/clients/{{ kc_client_current.id }}/protocol-mappers/models"
headers: "{{ kc_headers }}"
method: POST
body_format: json
body: "{{ kc_mapper_desired }}"
status_code: 201
when: kc_mapper_matches | length == 0
changed_when: true
- name: Update existing mapper on drift
ansible.builtin.uri:
url: "{{ kc_api }}/clients/{{ kc_client_current.id }}/protocol-mappers/models/{{ kc_mapper_matches[0].id }}"
headers: "{{ kc_headers }}"
method: PUT
body_format: json
body: "{{ kc_mapper_matches[0] | combine(kc_mapper_desired, recursive=true) }}"
status_code: 204
when:
- kc_mapper_matches | length == 1
- (kc_mapper_matches[0] | combine(kc_mapper_desired, recursive=true)) != kc_mapper_matches[0]
changed_when: true
+37
View File
@@ -0,0 +1,37 @@
- name: Check platform and required configuration
ansible.builtin.assert:
that:
- ansible_facts.os_family == 'Debian'
- not ansible_check_mode
- groups['keycloak'] | length == 1
- keycloak_base_url is match('^https://[^/]+$')
- pve_oidc_issuer == keycloak_base_url ~ '/realms/' ~ keycloak_realm
- pve_realm is match('^[A-Za-z0-9][A-Za-z0-9._-]*$')
- keycloak_realm is match('^[A-Za-z0-9][A-Za-z0-9._-]*$')
- pve_roles | length == pve_roles | unique | length
- "'NoAccess' not in pve_roles"
- keycloak_sso_idle | int > 0
- keycloak_sso_max | int >= keycloak_sso_idle | int
- keycloak_client_idle | int > 0
- keycloak_client_max | int >= keycloak_client_idle | int
- keycloak_client_idle | int <= keycloak_sso_idle | int
- keycloak_client_max | int <= keycloak_sso_max | int
- pve_redirect_uris | length > 0
fail_msg: 'Debian/Ubuntu, one Keycloak host, consistent HTTPS issuer and positive session values required. Check mode is unsupported.'
- name: Validate secret variables without logging their values
ansible.builtin.assert:
that:
- keycloak_admin_username | length > 0
- keycloak_admin_password | length > 0
- keycloak_client_secret | length >= 16
- keycloak_client_secret | length <= 256
- keycloak_client_secret == keycloak_client_secret | trim
- "'\\n' not in keycloak_client_secret"
- java_cacerts_password | length > 0
no_log: true
- name: Require exact HTTPS redirect URIs
ansible.builtin.assert:
that:
- item is match('^https://[^/]+/$')
- "'*' not in item"
loop: "{{ pve_redirect_uris }}"
+70
View File
@@ -0,0 +1,70 @@
- name: Check PVE version
ansible.builtin.command: pveversion
register: pve_version
changed_when: false
- name: Require PVE 9
ansible.builtin.assert:
that: "'pve-manager/9.' in pve_version.stdout"
- name: Verify OIDC discovery using PVE system CA trust
ansible.builtin.uri:
url: "{{ pve_oidc_issuer }}/.well-known/openid-configuration"
validate_certs: true
ca_path: "{{ system_ca_bundle }}"
use_proxy: false
follow_redirects: none
register: oidc_discovery
- name: Require exact issuer match
ansible.builtin.assert:
that: oidc_discovery.json.issuer == pve_oidc_issuer
- name: Read PVE realms
ansible.builtin.command: pveum realm list --output-format json
register: pve_realms
changed_when: false
- name: Select existing realm
ansible.builtin.set_fact:
pve_realm_matches: "{{ pve_realms.stdout | from_json | selectattr('realm', 'equalto', pve_realm) | list }}"
- name: Prevent changing another realm type
ansible.builtin.assert:
that: pve_realm_matches | length == 0 or pve_realm_matches[0].type == 'openid'
- name: Read full existing realm configuration
ansible.builtin.command:
argv: [pvesh, get, "/access/domains/{{ pve_realm }}", --output-format, json]
register: pve_realm_read
when: pve_realm_matches | length > 0
changed_when: false
no_log: true
- name: Define managed PVE realm settings
ansible.builtin.set_fact:
pve_desired:
issuer-url: "{{ pve_oidc_issuer }}"
client-id: "{{ keycloak_client_id }}"
autocreate: 1
groups-claim: groups
groups-autocreate: 1
groups-overwrite: 1
query-userinfo: 1
username-claim: preferred_username
pve_existing: "{{ (pve_realm_read.stdout | default('{}')) | from_json }}"
pve_drift: false
no_log: true
- name: Compare managed PVE fields
ansible.builtin.set_fact:
pve_drift: true
when: pve_existing.get(item.key, '') | string != item.value | string
loop: "{{ pve_desired | dict2items }}"
no_log: true
- name: Require compatible immutable username claim
ansible.builtin.assert:
that: pve_realm_matches | length == 0 or pve_existing.get('username-claim', '') == 'preferred_username'
fail_msg: 'Existing realm has a different immutable username-claim. See README migration guidance; automatic realm deletion is disabled.'
- name: Create or update PVE realm when configuration or key differs
ansible.builtin.command:
argv: "{{ ['pveum', 'realm', ('modify' if pve_realm_matches | length > 0 else 'add'), pve_realm] + ([] if pve_realm_matches | length > 0 else ['--type', 'openid', '--username-claim', 'preferred_username']) + ['--issuer-url', pve_oidc_issuer, '--client-id', keycloak_client_id, '--client-key', keycloak_client_secret, '--autocreate', '1', '--groups-claim', 'groups', '--groups-autocreate', '1', '--groups-overwrite', '1', '--query-userinfo', '1'] }}"
when: pve_realm_matches | length == 0 or pve_drift or pve_existing.get('client-key', '') != keycloak_client_secret
no_log: true
changed_when: true
- name: Clear in-memory key result
ansible.builtin.set_fact:
pve_existing: {}
pve_realm_read: {}
no_log: true