Files
syno-scripts/PVE-IDM
2026-09-08 22:03:32 +02:00
..
2026-09-08 17:05:36 +02:00
2026-09-08 17:05:36 +02:00
2026-09-08 17:05:36 +02:00
2026-09-08 17:05:36 +02:00
2026-09-08 17:05:36 +02:00
2026-09-08 22:03:32 +02:00
2026-09-08 22:03:32 +02:00
2026-09-08 17:05:36 +02:00
2026-09-08 22:03:32 +02:00
2026-09-08 22:03:32 +02:00
2026-09-08 22:03:32 +02:00
2026-09-08 17:05:36 +02:00
2026-09-08 22:03:32 +02:00

PVE 9 + Keycloak OIDC für HEIMLAN

Version: 1.1.0 · Änderungsprotokoll · Versionsdatei

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

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

Interaktive Einrichtung (empfohlen)

Nach Installation/Aktivierung der unten beschriebenen Ansible-Python-Umgebung:

python3 setup.py

Der Assistent fragt alle konfigurierbaren Verbindungs- und Setup-Werte ab:

  • PVE- und Keycloak-Inventory-Namen, IP/DNS-Adressen, SSH-Ports, Benutzer, private SSH-Key-Pfade und sudo-Zielbenutzer.
  • Ob SSH- und sudo-Passwörter beim Ansible-Lauf abgefragt werden sollen.
  • HTTPS-Adressen, Issuer, Realms, Client-IDs und erlaubte PVE-Browser-URLs.
  • Alle vier Session-Zeiten in Sekunden, CA-Datei/Fingerprint, System- und Java-Truststore-Pfade.
  • Keycloak-Installationspfad, Dienst, Benutzer/Gruppe, Java-Keytool und CA-Alias.
  • Zu verwaltende PVE-Rollen und sämtliche erforderlichen Secrets.

Enter übernimmt den angezeigten Standardwert. Secrets werden verdeckt mit Bestätigung abgefragt. Ein zusätzliches Vault-Passwort verschlüsselt die Zugangsdaten direkt über Ansible Vault; Klartext-Secrets und Vault-Passwort werden nicht in temporäre Dateien geschrieben. Der Assistent benötigt ein interaktives macOS-/Linux-Terminal.

Die Antworten landen mit Dateirechten 0600 in inventory/hosts.local.yml, group_vars/all.yml und der verschlüsselten group_vars/vault.yml. Alle drei Dateien sind von Git ausgeschlossen. Die .yml-Konfigurationsdateien verwenden JSON-Syntax, die Ansible als gültiges YAML liest. Die CA-Datei bleibt am eingegebenen lokalen Pfad.

Bei einer erneuten Einrichtung fragt der Assistent vor dem Ersetzen vorhandener Konfiguration nach; bisherige Werte werden nicht eingelesen. Alle Parameter dann neu eingeben. Nach dem Speichern kann das Setup direkt gestartet werden. Standardmäßig werden zunächst nur die Dateien erstellt. Den angezeigten Startbefehl verwenden:

ansible-playbook -i inventory/hosts.local.yml playbook/site.yml --ask-vault-pass
# Nach dem ersten OIDC-Login:
ansible-playbook -i inventory/hosts.local.yml playbook/acl.yml

Bei Bedarf --ask-pass und/oder --ask-become-pass ergänzen; der Assistent fügt diese Optionen beim direkten Start entsprechend den Antworten hinzu. Passwortbasierter SSH-Zugriff kann auf dem Controller zusätzliche SSH-Unterstützung wie sshpass erfordern; ein SSH-Key oder SSH-Agent ist ebenfalls möglich.

Die vorgegebenen OIDC-Flags, Claim-Namen, TLS-Verifikation und der ACL-Pfad / bleiben entsprechend den Projektanforderungen fest. Es werden weiterhin bestehende Hosts und eine installierte Keycloak-Instanz vorausgesetzt.

Einrichtung und Start (manuell)

Alle Befehle im entpackten Verzeichnis ausführen:

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:

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.
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:
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:

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