diff --git a/PVE-IDM/.gitignore b/PVE-IDM/.gitignore index df1678d..6726318 100644 --- a/PVE-IDM/.gitignore +++ b/PVE-IDM/.gitignore @@ -9,3 +9,8 @@ files/*.crt .vault-pass* .vault_pass* vault-password* + +# Interaktiv erzeugte Hostkonfiguration +inventory/hosts.local.yml +__pycache__/ +.pve-idm-* diff --git a/PVE-IDM/CHANGELOG.md b/PVE-IDM/CHANGELOG.md index 68f8a23..1674092 100644 --- a/PVE-IDM/CHANGELOG.md +++ b/PVE-IDM/CHANGELOG.md @@ -1,5 +1,13 @@ # Änderungsprotokoll +## [1.1.0] – 2026-09-08 + +- Interaktiver Einrichtungsassistent `setup.py` für Host/IP, SSH, OIDC, CA/Java, + Session-Zeiten, Rollen und Secrets. +- Verdeckte Secret-Eingabe und direkte Vault-Verschlüsselung ohne Klartextdateien. +- Lokales Inventory mit Git-Ausschluss und optionalem direktem Playbook-Start. +- Tests für Eingaben, Dateirechte und echten Vault-Roundtrip. + ## [1.0.0] – 2026-09-08 Erste Version des Ansible-Setups für PVE 9 und Keycloak OIDC. diff --git a/PVE-IDM/README.md b/PVE-IDM/README.md index 13b6fe3..8f46073 100644 --- a/PVE-IDM/README.md +++ b/PVE-IDM/README.md @@ -1,6 +1,6 @@ # PVE 9 + Keycloak OIDC für HEIMLAN -Version: **1.0.0** · [Änderungsprotokoll](CHANGELOG.md) · [Versionsdatei](VERSION) +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`. @@ -25,7 +25,54 @@ playbook/acl.yml # spätere ACL-Zuordnung nach Login tasks/{preflight,ca,java,keycloak,keycloak_group,keycloak_mapper,pve,acl}.yml ``` -## Einrichtung und Start +## 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: diff --git a/PVE-IDM/VERSION b/PVE-IDM/VERSION index 3eefcb9..9084fa2 100644 --- a/PVE-IDM/VERSION +++ b/PVE-IDM/VERSION @@ -1 +1 @@ -1.0.0 +1.1.0 diff --git a/PVE-IDM/setup.py b/PVE-IDM/setup.py new file mode 100644 index 0000000..1cf163d --- /dev/null +++ b/PVE-IDM/setup.py @@ -0,0 +1,280 @@ +#!/usr/bin/env python3 +"""Interactive configuration for PVE-IDM; Python standard library only.""" +import getpass +import ipaddress +import json +import os +from pathlib import Path +import re +import shutil +import subprocess +import sys +import tempfile +from urllib.parse import urlsplit + +ROOT = Path(__file__).resolve().parent +ROLES = ['Administrator', 'PVEAdmin', 'PVEAuditor', 'PVEDatastoreAdmin', + 'PVEDatastoreUser', 'PVEMappingAdmin', 'PVEMappingUser', 'PVEPoolAdmin', + 'PVEPoolUser', 'PVESDNAdmin', 'PVESDNUser', 'PVESysAdmin', + 'PVETemplateUser', 'PVEUserAdmin', 'PVEVMAdmin', 'PVEVMUser'] + + +def ask(label, default='', validate=None): + while True: + value = input(f'{label}' + (f' [{default}]' if default != '' else '') + ': ').strip() + value = value or str(default) + try: + if validate: + validate(value) + return value + except ValueError as exc: + print(f'Bitte korrigieren: {exc}') + + +def required(value): + if not value or any(c in value for c in '\r\n\x00'): + raise ValueError('Ein gültiger Wert ist erforderlich.') + + +def identifier(value): + if not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]*', value): + raise ValueError('Nur Buchstaben, Ziffern, Punkt, Unterstrich und Bindestrich.') + + +def address(value): + required(value) + try: + ipaddress.ip_address(value) + return + except ValueError: + pass + if not re.fullmatch(r'[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?', value): + raise ValueError('IP-Adresse oder DNS-Hostname ohne Port/Protokoll eingeben.') + if re.fullmatch(r'[0-9.]+', value): + raise ValueError('Ungültige IP-Adresse.') + + +def integer(value, maximum=2147483647): + if not value.isdigit() or not 1 <= int(value) <= maximum: + raise ValueError(f'Ganze Zahl zwischen 1 und {maximum}.') + + +def https_url(value, root=False): + parsed = urlsplit(value) + try: + port = parsed.port + except ValueError as exc: + raise ValueError('Ungültiger Port.') from exc + if (parsed.scheme != 'https' or not parsed.hostname or parsed.username or + parsed.password or parsed.query or parsed.fragment or '*' in value or + any(c.isspace() for c in value)): + raise ValueError('Exakte HTTPS-Adresse ohne Zugangsdaten, Wildcard oder Query erforderlich.') + if port is not None and not 1 <= port <= 65535: + raise ValueError('Ungültiger Port.') + if root and parsed.path != '/': + raise ValueError('PVE-Browser-Adresse muss mit / enden und darf keinen Unterpfad enthalten.') + if not root and parsed.path: + raise ValueError('Keycloak-Basisadresse ohne Unterpfad und ohne abschließenden /.') + + +def absolute_path(value): + if not value.startswith('/') or '\x00' in value: + raise ValueError('Absoluten Pfad eingeben.') + + +def local_file(value): + if not Path(value).expanduser().is_file(): + raise ValueError('Datei auf diesem Mac/Controller nicht gefunden.') + + +def yes(label, default=False): + return ask(label + ' (j/n)', 'j' if default else 'n', + lambda v: None if v.lower() in ('j', 'n') else invalid('j oder n eingeben.')).lower() == 'j' + + +def invalid(message): + raise ValueError(message) + + +def secret(label, minimum=1, maximum=4096): + while True: + value = getpass.getpass(label + ': ') + if not minimum <= len(value) <= maximum or '\n' in value or '\r' in value: + print(f'Bitte {minimum} bis {maximum} Zeichen ohne Zeilenumbruch eingeben.') + continue + if getpass.getpass('Zur Bestätigung erneut eingeben: ') != value: + print('Die Eingaben stimmen nicht überein.') + continue + return value + + +def host(kind, alias, target, user): + print(f'\n{kind}: SSH-Verbindung (unabhängig von der HTTPS-Browser-Adresse)') + alias = ask('Inventory-Name', alias, identifier) + data = { + 'ansible_host': ask('IP-Adresse oder DNS-Hostname', target, address), + 'ansible_port': int(ask('SSH-Port', '22', lambda v: integer(v, 65535))), + 'ansible_user': ask('SSH-Benutzer', user, identifier), + 'ansible_become': True, + 'ansible_become_user': ask('Zielbenutzer für sudo/become', 'root', identifier), + } + key = ask('SSH-Key auf diesem Mac (leer = SSH-Agent/Standard-Key)', '', + lambda v: local_file(v) if v else None) + if key: + data['ansible_ssh_private_key_file'] = str(Path(key).expanduser().resolve()) + return alias, data + + +def encrypt_vault(payload, password, executable): + # Anonymous pipe: no plaintext password file and no secret command arguments. + read_fd, write_fd = os.pipe() + try: + os.write(write_fd, (password + '\n').encode()) + os.close(write_fd) + write_fd = None + result = subprocess.run( + [executable, 'encrypt', '--vault-password-file', f'/dev/fd/{read_fd}', '--output', '-'], + input=json.dumps(payload).encode(), stdout=subprocess.PIPE, stderr=subprocess.PIPE, + pass_fds=(read_fd,), check=False) + if result.returncode or not result.stdout.startswith(b'$ANSIBLE_VAULT;'): + raise RuntimeError('Vault-Verschlüsselung fehlgeschlagen; keine Konfiguration gespeichert.') + return result.stdout + finally: + os.close(read_fd) + if write_fd is not None: + os.close(write_fd) + + +def atomic_write(path, content): + path.parent.mkdir(parents=True, exist_ok=True) + fd, temporary = tempfile.mkstemp(prefix='.pve-idm-', dir=path.parent) + try: + with os.fdopen(fd, 'wb') as stream: + stream.write(content) + os.replace(temporary, path) + finally: + if os.path.exists(temporary): + os.unlink(temporary) + + +def main(): + os.chdir(ROOT) + if not sys.stdin.isatty(): + raise RuntimeError('Bitte interaktiv in einem Terminal starten: python3 setup.py') + vault_bin = shutil.which('ansible-vault') + if not vault_bin: + raise RuntimeError('Ansible fehlt. Zuerst die Python-Umgebung aktivieren und ansible-core installieren (README).') + paths = [ROOT / 'inventory/hosts.local.yml', ROOT / 'group_vars/all.yml', ROOT / 'group_vars/vault.yml'] + print('PVE-IDM Einrichtung · Enter übernimmt den angezeigten Standardwert.\n' + 'Konfiguriert bestehende PVE-/Keycloak-Installationen; erzeugt keine VM.\n' + 'Vorhandene Werte werden nicht eingelesen; bei erneutem Start alles neu eingeben.') + if any(p.exists() for p in paths): + if not yes('Vorhandene lokale Konfiguration vollständig ersetzen?'): + print('Abgebrochen; vorhandene Dateien bleiben erhalten.') + return + pve_alias, pve_host = host('PVE', 'ts01', 'ts01.heim.lan', 'root') + kc_alias, kc_host = host('Keycloak-VM', 'keycloak-vm', 'keycloak.service.heim.lan', 'ansible') + if pve_alias == kc_alias: + raise RuntimeError('Die beiden Inventory-Namen müssen verschieden sein.') + ask_ssh = yes('SSH-Passwort beim späteren Ansible-Lauf abfragen?') + ask_become = yes('sudo-Passwort beim späteren Ansible-Lauf abfragen?') + print('\nOIDC und Browser-Adressen (TLS-Zertifikate müssen zu diesen Namen passen)') + config = {} + config['keycloak_base_url'] = ask('Keycloak HTTPS-Basisadresse inkl. Port', + 'https://keycloak.service.heim.lan:8443', https_url) + for key, label, default in [ + ('keycloak_realm', 'Keycloak-Realm', 'main.heim.lan'), + ('pve_realm', 'PVE-Realm und Gruppensuffix', 'main.heim.lan'), + ('keycloak_client_id', 'Keycloak Client-ID', 'PVE-SERVER'), + ('keycloak_admin_realm', 'Admin-Realm', 'master'), + ('keycloak_admin_client_id', 'Admin-Client-ID', 'admin-cli')]: + config[key] = ask(label, default, identifier) + issuer = config['keycloak_base_url'] + '/realms/' + config['keycloak_realm'] + config['pve_oidc_issuer'] = ask('OIDC-Issuer (muss zur Basisadresse/Realm passen)', issuer, + lambda v: None if v == issuer else invalid('Issuer muss ' + issuer + ' sein.')) + def redirects(value): + for url in value.split(','): + https_url(url.strip(), root=True) + config['pve_redirect_uris'] = list(dict.fromkeys(u.strip() for u in ask( + 'PVE-Browser-URLs, mehrere mit Komma trennen', 'https://ts01.heim.lan:8006/', redirects).split(','))) + print('\nSessions in Sekunden: 900 = 15 Minuten; 28800 = 8 Stunden') + while True: + for key, label, default in [ + ('keycloak_sso_idle', 'SSO Idle', '900'), ('keycloak_sso_max', 'SSO Max', '28800'), + ('keycloak_client_idle', 'Client Idle', '900'), ('keycloak_client_max', 'Client Max', '28800')]: + config[key] = int(ask(label, default, integer)) + if (config['keycloak_sso_idle'] <= config['keycloak_sso_max'] and + config['keycloak_client_idle'] <= config['keycloak_client_max'] and + config['keycloak_client_idle'] <= config['keycloak_sso_idle'] and + config['keycloak_client_max'] <= config['keycloak_sso_max']): + break + print('Max muss mindestens Idle sein; Client-Werte dürfen SSO-Werte nicht überschreiten. Erneut eingeben.') + print('\nCA und Installationspfade') + config['heimlan_ca_src'] = str(Path(ask('Root-CA-Datei auf diesem Mac/Controller', + str(ROOT / 'files/HEIMLAN_RootCA.crt'), local_file)).expanduser().resolve()) + config['heimlan_ca_sha256'] = ask('Optionaler geprüfter CA-SHA256-Fingerprint (leer = keiner)', '', + lambda v: None if not v or re.fullmatch(r'(?:[0-9a-fA-F]{2}:){31}[0-9a-fA-F]{2}', v) + else invalid('SHA256 als 32 Hex-Paare mit Doppelpunkten eingeben.')) + for key, label, default in [ + ('system_ca_bundle', 'System-CA-Bundle auf den Zielhosts', '/etc/ssl/certs/ca-certificates.crt'), + ('keycloak_home', 'Keycloak-Installation auf der VM', '/opt/keycloak'), + ('java_cacerts_path', 'Truststore der tatsächlich verwendeten JVM', '/etc/ssl/certs/java/cacerts'), + ('java_keytool', 'Java-keytool auf der VM', '/usr/bin/keytool')]: + config[key] = ask(label, default, absolute_path) + for key, label, default in [ + ('keycloak_service', 'Keycloak systemd-Dienst', 'keycloak'), + ('keycloak_user', 'Keycloak Servicebenutzer', 'keycloak'), + ('keycloak_group', 'Keycloak Servicegruppe', 'keycloak'), + ('java_ca_alias', 'Verwalteter Java-CA-Alias', 'heimlan-rootca-ansible')]: + config[key] = ask(label, default, identifier) + def roles(value): + selected = [v.strip() for v in value.split(',')] + if not selected or any(v not in ROLES for v in selected) or len(set(selected)) != len(selected): + invalid('Nur eindeutige Rollen aus der angezeigten Liste verwenden; NoAccess ist ausgeschlossen.') + config['pve_roles'] = [v.strip() for v in ask('Zu verwaltende PVE-Rollen, mit Komma trennen', + ','.join(ROLES), roles).split(',')] + print('\nZugangsdaten (Passwörter werden nicht angezeigt)') + secrets = {'vault_keycloak_admin_username': ask('Keycloak Admin-Benutzername', '', required)} + secrets['vault_keycloak_admin_password'] = secret('Keycloak Admin-Passwort') + while True: + secrets['vault_keycloak_client_secret'] = secret('Gemeinsames PVE/Keycloak Client-Secret', 16, 256) + if secrets['vault_keycloak_client_secret'] == secrets['vault_keycloak_client_secret'].strip(): + break + print('Client-Secret darf keine äußeren Leerzeichen enthalten.') + secrets['vault_java_cacerts_password'] = secret('Bestehendes Java-Truststore-Passwort') + vault_password = secret('Passwort zum Verschlüsseln der lokalen Ansible-Vault-Datei', 8) + for key in ('keycloak_admin_username', 'keycloak_admin_password', 'keycloak_client_secret', 'java_cacerts_password'): + config[key] = '{{ vault_' + key + ' }}' + inventory = {'all': {'children': { + 'pve': {'hosts': {pve_alias: pve_host}}, 'keycloak': {'hosts': {kc_alias: kc_host}}}}} + print(f'\nPVE: {pve_alias} → {pve_host["ansible_host"]}:{pve_host["ansible_port"]}\n' + f'Keycloak: {kc_alias} → {kc_host["ansible_host"]}:{kc_host["ansible_port"]}\n' + f'Issuer: {issuer}\nKonfiguration wird lokal gespeichert; Secrets nur verschlüsselt.') + if not yes('Konfiguration jetzt speichern?', True): + print('Abgebrochen; keine Dateien gespeichert.') + return + encrypted = encrypt_vault(secrets, vault_password, vault_bin) + # JSON is valid YAML and avoids interpolation/quoting of user-entered values. + atomic_write(paths[0], (json.dumps(inventory, indent=2) + '\n').encode()) + atomic_write(paths[1], (json.dumps(config, indent=2) + '\n').encode()) + atomic_write(paths[2], encrypted) + command = ['ansible-playbook', '-i', 'inventory/hosts.local.yml', 'playbook/site.yml', '--ask-vault-pass'] + if ask_ssh: + command.append('--ask-pass') + if ask_become: + command.append('--ask-become-pass') + print('\nGespeichert. Später starten mit:\n ' + ' '.join(command)) + print('ACL-Lauf nach dem ersten Login:\n ansible-playbook -i inventory/hosts.local.yml playbook/acl.yml') + if yes('Setup jetzt auf den Zielhosts ausführen?'): + subprocess.run(command, check=True) + + +if __name__ == '__main__': + try: + main() + except (KeyboardInterrupt, EOFError): + print('\nAbgebrochen.', file=sys.stderr) + sys.exit(130) + except (RuntimeError, OSError, subprocess.CalledProcessError) as exc: + print(f'Fehler: {exc}', file=sys.stderr) + sys.exit(1) diff --git a/PVE-IDM/tests/test_setup.py b/PVE-IDM/tests/test_setup.py new file mode 100644 index 0000000..0addf5a --- /dev/null +++ b/PVE-IDM/tests/test_setup.py @@ -0,0 +1,60 @@ +import importlib.util +import os +from pathlib import Path +import shutil +import subprocess +import tempfile +import unittest + +spec = importlib.util.spec_from_file_location('wizard', Path(__file__).resolve().parents[1] / 'setup.py') +wizard = importlib.util.module_from_spec(spec) +spec.loader.exec_module(wizard) + + +class SetupTests(unittest.TestCase): + def test_addresses(self): + for value in ('192.168.1.10', '2001:db8::1', 'ts01.heim.lan'): + wizard.address(value) + for value in ('999.1.1.1', 'https://ts01', 'ts01:22', ''): + with self.assertRaises(ValueError): + wizard.address(value) + + def test_https(self): + wizard.https_url('https://keycloak.service.heim.lan:8443') + wizard.https_url('https://ts01.heim.lan:8006/', root=True) + for value in ('http://ts01/', 'https://user:secret@ts01/', 'https://ts01/*', + 'https://ts01:99999/', 'https://ts01/?a=b', 'https://ts01/admin'): + with self.assertRaises(ValueError): + wizard.https_url(value, root=True) + + def test_atomic_file_permissions(self): + with tempfile.TemporaryDirectory() as folder: + target = Path(folder) / 'all.yml' + wizard.atomic_write(target, b'{}') + self.assertEqual(target.read_bytes(), b'{}') + self.assertEqual(target.stat().st_mode & 0o777, 0o600) + self.assertEqual(len(list(Path(folder).iterdir())), 1) + + @unittest.skipUnless(shutil.which('ansible-vault'), 'ansible-vault not installed') + def test_real_vault_roundtrip(self): + payload = {'test': 'fake-test-value-with-umlaut-ä'} + password = 'test-password-only' + executable = shutil.which('ansible-vault') + encrypted = wizard.encrypt_vault(payload, password, executable) + self.assertTrue(encrypted.startswith(b'$ANSIBLE_VAULT;')) + self.assertNotIn(payload['test'].encode(), encrypted) + read_fd, write_fd = os.pipe() + try: + os.write(write_fd, (password + '\n').encode()) + os.close(write_fd) + result = subprocess.run([executable, 'decrypt', '--vault-password-file', + f'/dev/fd/{read_fd}', '--output', '-'], + input=encrypted, capture_output=True, + pass_fds=(read_fd,), check=True) + self.assertEqual(wizard.json.loads(result.stdout), payload) + finally: + os.close(read_fd) + + +if __name__ == '__main__': + unittest.main()