Stand September 2026 (Server 1.0.31, Agent 1.0.36)

Geräte ohne Domäne (API-Key)

1. Was ist das?

ZeroPortal authentifiziert Geräte und Benutzer standardmäßig per Kerberos; ein Domänenmitglied braucht dafür keine Schlüsselverwaltung. Dieses Dokument beschreibt den zweiten Weg für Geräte, die keiner Domäne angehören – Arbeitsgruppenrechner, ein Gerät in einer Filiale ohne Domäne, das Notebook eines Dienstleisters.

Sie erzeugen im Portal ein Rollout-Token. Das Token ist kein Geheimnis – es erlaubt nur, einen eigenen Schlüssel anzufordern, und darf deshalb in einer Installationszeile mitreisen. Beim ersten Abgleich tauscht der Agent es gegen einen dauerhaften Maschinenschlüssel; ein lokal angemeldeter Benutzer erhält zusätzlich einen eigenen Benutzerschlüssel. Damit bezieht das Gerät Pakete und Richtlinien wie ein Domänenmitglied und erscheint im Portal unter Bekannte Clients.

Der Weg ist experimentell: funktionsfähig, aber für Pilotinstallationen und Einzelgeräte gedacht, nicht für einen Großrollout. Er liefert MSIX-Pakete im Benutzerkontext; App-V, App Attach und maschinenweite Installationen sind auf solchen Geräten nicht möglich (Abschnitt 4.4).

2. Wozu ist das gut?

• Arbeitsgruppen- und Einzelgeräte. Kiosk, Messe-Notebook, Laborrechner – dieselben Pakete und Richtlinien wie die Domänenclients.
• Geräte in einer DMZ oder Filiale ohne Domänencontroller. HTTPS zum Portal geht, ein Kerberos-Ticket nicht.
• Notebooks von Dienstleistern. Ein eigener Schlüssel, den Sie jederzeit einzeln sperren können, ohne die Domäne anzufassen.
• Testumgebungen. Eine frische VM ohne Domäne ist in Minuten angebunden.

Ein Portal bedient Domänenclients per Kerberos und schlüsselbasierte Clients nebeneinander.

3. Wie nutze ich das?

Voraussetzungen:

3.1 Portal vorbereiten

Auf der Seite Globale Konfiguration → Agent-Registrierung (nur für Voll-Administratoren):

1. In der Karte Rollout-Token den Schalter Schlüsselbasierter Zugang einschalten. Solange er aus ist, werden jede Registrierung und alle ausgegebenen Schlüssel abgewiesen.
2. Ein Token anlegen: Name (z. B. „Rollout Standort Hannover"), Gültig (Tage) – vorbelegt mit 14, erlaubt sind 1 bis 365 – und Erstellen. Der Dialog zeigt den Tokenwert (beginnt mit zpe_) und die fertige Installationszeile (Mit dem Installer ausrollen); die Gruppenrichtlinien-Variante ist nur für domänengebundene Geräte gedacht.
3. Tokenwert anzeigen blendet den Wert später erneut ein – in einer Hochverfügbarkeits-Installation nur auf dem Knoten, auf dem das Token erstellt wurde.
4. Die Tabelle zeigt je Token, ob sein Registrierungsfenster offen oder geschlossen ist und bis wann es gilt. Für 14 Tage wieder öffnen verlängert ein abgelaufenes Fenster und behält den Tokenwert; Öffnen/schließen schaltet das Fenster von Hand.

Per PowerShell (Modul des Servers): Get-, New-, Set-, Remove-ZeroPortalEnrollmentToken sowie Get- und Set-ZeroPortalApiClient.

3.2 Agent installieren

Die Zeile aus dem Token-Dialog enthält die Portal-URL, das Token und die drei Sync-Schalter, die ab Werk aus sind. Für ein selbstsigniertes Portalzertifikat hängen Sie TRUSTCERT=1 an, für eine stille Installation /qn:

msiexec /i ZeroPortalAgent.msi SERVER=https://portal.firma.tld:8080 ENROLLTOKEN=zpe_... MSIXSYNC=1 POLICYSYNC=1 TRUSTCERT=1 /qn

APPVSYNC=1 können Sie weglassen – App-V ist auf solchen Geräten nicht nutzbar. Die Schalter sind dauerhaft: Ein späteres Update ohne die Parameter nimmt sie nicht zurück.

Zertifikat. Mit TRUSTCERT=1 installiert der Dienst beim ersten Maschinen-Sync ein Portalzertifikat, dessen Kette nicht validiert, in die vertrauenswürdigen Stammzertifizierungsstellen des Computers (Trust on first use – nur für Server aus der eigenen Serverliste; ein regulär gültiges Zertifikat wird nie angefasst; Ereignis 2013). Alternativ importieren Sie das Zertifikat von Hand in den Computerspeicher – die vertrauenswürdigen Sites des Browsers genügen nicht. Nachträglich: Set-ZPAgentConfiguration -TrustServerCertificate $true.

Was danach passiert. 30 Sekunden nach dem Dienststart läuft der erste Maschinen-Sync: Der Agent fordert mit dem Token einen Maschinenschlüssel an (Ereignis 2510), das Gerät erscheint unter Bekannte Clients. Beim Benutzer-Sync holt sich ein lokales Benutzerkonto einen eigenen Schlüssel und erscheint unter Bekannte Benutzer als benutzer@gerätename.

3.3 Lese-Konto und Paketfreigabe

Das Gerät kann die Paketfreigabe nicht mit einer Domänenidentität lesen. Richten Sie keinen anonymen Zugriff ein, sondern ein lokales Konto auf dem Dateiserver, das ausschließlich lesen darf.

1. Lokales Konto auf dem Dateiserver anlegen (z. B. PackageShare_RO, Kennwort läuft nie ab):

2. Diesem Konto im Paketordner das NTFS-Recht Lesen, Ausführen geben. Auf Freigabeebene reicht der Eintrag Jeder aus dem Administrationshandbuch (Kapitel 3, „Paketfreigabe einrichten“):

3.4 Richtlinie: SMB-Verbindung mit Zugangsdaten

Die Verbindung zur Freigabe baut der Agent über eine Laufwerks-Richtlinie auf. Die SMB-Sitzung gilt für die ganze Anmeldesitzung; die Paketbereitstellung erreicht den UNC-Pfad damit, ohne dass ein Laufwerk im Explorer erscheinen muss.

1. Unter Richtlinien mit Neuer Satz einen Richtliniensatz anlegen, z. B. „APIClients":

2. Den Geltungsbereich mit Bereich bearbeiten auf die Zielgeräte einschränken, z. B. per Computername mit Platzhalter (* und ?). Der Filter wird lokal ausgewertet und braucht kein Active Directory:

3. Richtlinie hinzufügen → Vorlage Laufwerke verbinden:

4. Den Laufwerkseintrag so füllen:

5. Den Satz auf Aktiv schalten. Beim nächsten Benutzer-Sync steht im Agent-Log:

INF [2614] Policy SMB session established: \\fileserver\pakete$

Sicherheit. Das Passwort wird verschlüsselt gespeichert und übertragen, aber jedes Gerät, das die Richtlinie erhält, kann es lesen – Verschleierung, keine Geheimhaltung (dieselbe Lektion wie cpassword in Gruppenrichtlinien). Deshalb gehört in diese Richtlinie ausschließlich ein Konto mit reinen Leserechten, niemals ein privilegiertes; mit Leserechten auf Paketdateien ist es kein lohnendes Ziel.

3.5 Pakete berechtigen und prüfen

• Berechtigen: Auf der Seite des MSIX-Pakets in der Karte AD-Berechtigungen über Hinzufügen die Quelle API-Clients wählen – dort stehen die registrierten Geräte und Benutzer – oder eine Portalgruppe, in der Sie diese Prinzipale zusammenfassen. Import und Veröffentlichung beschreibt MSIX-Pakete verteilen.
• Portal: Unter Bekannte Clients zeigt das Gerät Schlüssel: aktiv, das verwendete Token und unter Letzter Sync einen frischen Zeitstempel; der lokale Benutzer steht unter Bekannte Benutzer.
• Agent-Log (C:\ProgramData\NickIT\ZeroPortalAgent\Logs):

INF [2614] Policy SMB session established: \\fileserver\pakete$ INF [2400] AddPackage (current user): file://fileserver/pakete$/MSIX/... INF [2519] User sync done — installed=1 ... - Tray: Die Karte zeigt den Fortschritt. Minutenlange Installationen ohne Internetzugang erklärt Bekannte Fehlerbilder.

4. Regeln: wann wirkt was

4.1 Schlüsselmodell

• Der Maschinenschlüssel liegt DPAPI-geschützt im Maschinenzweig der Registry (nur mit Adminrechten lesbar), der Benutzerschlüssel im Benutzerzweig, geschützt für genau dieses Konto.
• Einen Benutzerschlüssel erhalten nur lokale Konten. Ein Domänenkonto hat bereits eine Identität und bekommt keinen Schlüssel – sonst würden seine AD-Gruppen nicht mehr greifen.
• Die Identität benutzer@gerätename ist an dieses Konto auf diesem Gerät gebunden; gleichnamige lokale Konten verschiedener Geräte bleiben getrennte Prinzipale.
• Ein gespeicherter Schlüssel hat Vorrang vor Kerberos; im Benutzerkontext der Benutzerschlüssel vor dem Maschinenschlüssel. Tritt ein Gerät später der Domäne bei, entfernen Sie den Maschinenschlüssel (Abschnitt 4.3), damit es wieder als Computerkonto auftritt.
• Der Agent registriert sich nur, wenn lokal kein Schlüssel gespeichert ist; ein vorhandener Schlüssel wird nie von selbst erneuert. Registriert sich dasselbe Gerät (erkannt an einer stabilen Maschinenkennung, die eine Umbenennung übersteht) oder derselbe Anmeldename erneut, behält es Prinzipal und Berechtigungen; der alte Schlüssel wird ersetzt. Das ist der Wiederherstellungsweg bei Schlüsselverlust.

4.2 Token-Fenster

• Ein Token registriert nur, solange sein Fenster offen und das Ablaufdatum nicht erreicht ist. Ein geschlossenes oder abgelaufenes Fenster verhindert neue Registrierungen – ausgegebene Schlüssel bleiben gültig, auch nach dem Löschen des Tokens.
• Für 14 Tage wieder öffnen behält den Tokenwert; verteilte Installationszeilen und Skripte funktionieren weiter.
• Der Schalter Schlüsselbasierter Zugang wird bei jeder Anfrage geprüft: Aus heißt sofort aus – für Registrierungen und für alle vorhandenen Schlüssel.

4.3 Deaktivieren oder Löschen

Unter Bekannte Clients gibt es zwei Eingriffe, die sich deutlich unterscheiden:

Deaktivieren ist der Griff für „vorübergehend aussperren", Löschen das Aufräumen für Geräte, die nicht wiederkommen. Das Löschen eines registrierten Benutzers unter Bekannte Benutzer entfernt ebenfalls dessen Schlüssel.

Soll ein gelöschtes Gerät wieder registriert werden, entfernen Sie den Schlüssel lokal – ein Cmdlet gibt es dafür nicht:

reg delete HKLM\SOFTWARE\NickIT\ZPAgent\Auth /v ApiKey /f
Restart-Service ZeroPortalAgent

Der Maschinen-Sync nach dem Neustart registriert das Gerät neu, sofern das Token noch gespeichert und sein Fenster offen ist. Für einen Benutzerschlüssel löschen Sie im Kontext des Benutzers den Wert ApiKey unter HKCU\SOFTWARE\NickIT\ZPAgent\Auth und stoßen den Benutzer-Sync an (Tray-Symbol oder Sync-ZPAgentPublishingServer -Method User).

4.4 Grenzen

• Nur MSIX, nur Benutzerkontext. Die Paketinstallation für den angemeldeten Benutzer nutzt dessen SMB-Sitzung. App Attach und maschinenweite Installationen laufen im Dienst als Systemkonto, das ohne Domäne keine Zugangsdaten zur Freigabe hat.
• App-V ist nicht möglich: Die App-V-Zuweisung nimmt ausschließlich AD-Gruppen an, und die Auslieferung liefe ebenfalls im Dienst.
• Richtlinienfilter auf AD-Gruppe oder Organisationseinheit treffen auf einem Arbeitsgruppengerät nie zu; Computername, IP-Bereich, Betriebssystem, Registrierungswert, Datei/Ordner und die übrigen lokal ausgewerteten Filter funktionieren.

4.5 Reihenfolge im Benutzer-Sync

Der Benutzer-Sync verarbeitet zuerst die Richtlinien, dann die Pakete. Laufwerke mit Synchron (Sync wartet) werden innerhalb des Richtlinienlaufs verbunden, asynchrone in einer Hintergrundspur mit 120-Sekunden-Wächter, auf die die Paketbereitstellung nicht wartet. Deshalb muss das Laufwerk mit den Zugangsdaten synchron sein. Die Agent-Einstellung Policy/AsyncDrivesPrinters = 0 schaltet die Hintergrundspur ganz ab.

4.6 Lizenz

Registrierte Geräte und Benutzer zählen wie Domänenclients im 90-Tage-Fenster der Lizenzierung; 30 Lizenzen sind enthalten. Ist keine Lizenz frei, lehnt das Portal die Lizenzbuchung ab, liefert aber weiter aus. Der Agent fragt alle vier Stunden erneut nach und zeigt dem Benutzer jedes Mal einen Hinweis. Details in Benutzer, Rechte, Lizenzen und Protokolle.

5. Betrieb und Fehlersuche

Wo Sie nachsehen:

• Portal: Globale Konfiguration → Agent-Registrierung – Tokenstatus, Bekannte Clients (Schlüssel aktiv/inaktiv, letzter Sync), Bekannte Benutzer.
• Agent-Log: C:\ProgramData\NickIT\ZeroPortalAgent\Logs. Ereignisse im Anhang.
• Portal-Log: C:\ProgramData\NickIT\ZPServer\Logs\ZeroPortalLogs.log. Jede Registrierung schreibt eine Zeile Enrollment: …; ein abgelehnter Schlüssel steht als ApiKey: rejected request from <IP> — <Grund>. Der Agent selbst erfährt den Grund nicht.

6. Anhang: Technische Referenz

Registrierung auf dem Gerät

Gruppenrichtlinie (nur für domänengebundene Geräte): Computerkonfiguration → Administrative Vorlagen → NickIT → ZeroPortal Agent → Authentifizierung → Registrierungstoken; ADMX-Vorlage unter C:\Program Files\NickIT\ZeroPortalAgent\admx.

Ereignisse im Agent-Log