Files
syno-scripts/PVE-IDM/README.md
T
2026-09-08 17:05:36 +02:00

146 lines
12 KiB
Markdown

# 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)