diff --git a/PVE-IDM/.gitignore b/PVE-IDM/.gitignore new file mode 100644 index 0000000..df1678d --- /dev/null +++ b/PVE-IDM/.gitignore @@ -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* diff --git a/PVE-IDM/CHANGELOG.md b/PVE-IDM/CHANGELOG.md new file mode 100644 index 0000000..68f8a23 --- /dev/null +++ b/PVE-IDM/CHANGELOG.md @@ -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. diff --git a/PVE-IDM/README.md b/PVE-IDM/README.md new file mode 100644 index 0000000..13b6fe3 --- /dev/null +++ b/PVE-IDM/README.md @@ -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 `-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) diff --git a/PVE-IDM/VALIDATION.md b/PVE-IDM/VALIDATION.md new file mode 100644 index 0000000..b8c58df --- /dev/null +++ b/PVE-IDM/VALIDATION.md @@ -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. diff --git a/PVE-IDM/VERSION b/PVE-IDM/VERSION new file mode 100644 index 0000000..3eefcb9 --- /dev/null +++ b/PVE-IDM/VERSION @@ -0,0 +1 @@ +1.0.0 diff --git a/PVE-IDM/ansible.cfg b/PVE-IDM/ansible.cfg new file mode 100644 index 0000000..0ff324d --- /dev/null +++ b/PVE-IDM/ansible.cfg @@ -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 diff --git a/PVE-IDM/files/README.md b/PVE-IDM/files/README.md new file mode 100644 index 0000000..55916fe --- /dev/null +++ b/PVE-IDM/files/README.md @@ -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. diff --git a/PVE-IDM/group_vars/all.yml.example b/PVE-IDM/group_vars/all.yml.example new file mode 100644 index 0000000..2c39ba3 --- /dev/null +++ b/PVE-IDM/group_vars/all.yml.example @@ -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 diff --git a/PVE-IDM/inventory/hosts.yml b/PVE-IDM/inventory/hosts.yml new file mode 100644 index 0000000..e6d2f78 --- /dev/null +++ b/PVE-IDM/inventory/hosts.yml @@ -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 diff --git a/PVE-IDM/playbook/acl.yml b/PVE-IDM/playbook/acl.yml new file mode 100644 index 0000000..a576632 --- /dev/null +++ b/PVE-IDM/playbook/acl.yml @@ -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 diff --git a/PVE-IDM/playbook/site.yml b/PVE-IDM/playbook/site.yml new file mode 100644 index 0000000..b6799eb --- /dev/null +++ b/PVE-IDM/playbook/site.yml @@ -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 diff --git a/PVE-IDM/tasks/acl.yml b/PVE-IDM/tasks/acl.yml new file mode 100644 index 0000000..c08e214 --- /dev/null +++ b/PVE-IDM/tasks/acl.yml @@ -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) diff --git a/PVE-IDM/tasks/ca.yml b/PVE-IDM/tasks/ca.yml new file mode 100644 index 0000000..0dea205 --- /dev/null +++ b/PVE-IDM/tasks/ca.yml @@ -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" diff --git a/PVE-IDM/tasks/java.yml b/PVE-IDM/tasks/java.yml new file mode 100644 index 0000000..2ccc577 --- /dev/null +++ b/PVE-IDM/tasks/java.yml @@ -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 diff --git a/PVE-IDM/tasks/keycloak.yml b/PVE-IDM/tasks/keycloak.yml new file mode 100644 index 0000000..4bfd006 --- /dev/null +++ b/PVE-IDM/tasks/keycloak.yml @@ -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: [] diff --git a/PVE-IDM/tasks/keycloak_group.yml b/PVE-IDM/tasks/keycloak_group.yml new file mode 100644 index 0000000..169ea60 --- /dev/null +++ b/PVE-IDM/tasks/keycloak_group.yml @@ -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 diff --git a/PVE-IDM/tasks/keycloak_mapper.yml b/PVE-IDM/tasks/keycloak_mapper.yml new file mode 100644 index 0000000..71dc0a1 --- /dev/null +++ b/PVE-IDM/tasks/keycloak_mapper.yml @@ -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 diff --git a/PVE-IDM/tasks/preflight.yml b/PVE-IDM/tasks/preflight.yml new file mode 100644 index 0000000..0281b7d --- /dev/null +++ b/PVE-IDM/tasks/preflight.yml @@ -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 }}" diff --git a/PVE-IDM/tasks/pve.yml b/PVE-IDM/tasks/pve.yml new file mode 100644 index 0000000..f87dde8 --- /dev/null +++ b/PVE-IDM/tasks/pve.yml @@ -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