193 lines
15 KiB
Markdown
193 lines
15 KiB
Markdown
# PVE 9 + Keycloak OIDC für HEIMLAN
|
|
|
|
Version: **1.1.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
|
|
```
|
|
|
|
## Interaktive Einrichtung (empfohlen)
|
|
|
|
Nach Installation/Aktivierung der unten beschriebenen Ansible-Python-Umgebung:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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)
|