Installation des OnPremise-Agenten

Update auf eine neue Version

Ab Version 1.5.19 ist das Aktualisieren des Agents im Grunde ein „Weiter, weiter, fertig“-Prozess. Der Installer darf nicht von einem Netzlaufwerk aus gestartet werden.

Aufgrund eines Fehlers im Installer der Version 1.13.* ist es leider nicht möglich, direkt auf diese Version zu aktualisieren. Daher muss die ältere Version zunächst deinstalliert werden, bevor die neue Version installiert werden kann.

1. Sichern Sie zunächst die Datei appsettings.json aus dem Programmverzeichnis unter C:\Program Files (x86)\STP AG\STP Documents OnPremise Agent. Sie enthält alle Konfigurationseinstellungen.
2. Deinstallieren Sie anschließend den „STP Documents On-Premise-Agent“ über „Programme und Features“ (oder Software) in der Windows-Systemsteuerung.
3. Danach kann der neue Agent installiert werden. Sie können entweder die Konfigurationswerte aus der gesicherten appsettings.json verwenden oder beliebige Werte während der Installation eingeben und die gesicherte appsettings.json nach Abschluss der Installation wiederherstellen.

Installation

Der STP.Documents On-Premise Agent verbindet den STP.Documents-Dienst in der STP Cloud mit dem STP.Documents.OnPremise-System auf dem Server der Kanzlei. Die Installation über den Installer ist einfacher als die alte Batch-Installation. Der Installer führt Sie mit einer grafischen Benutzeroberfläche durch den Installationsprozess.

1. Starten Sie das Setup (STP.Documents.OnpremiseAgent (...).exe) in einem lokalen Verzeichnis (nicht von einem Netzlaufwerk!). Bei einer Migration öffnen Sie die gespeicherte Konfigurationsdatei appsettings..json.

2. Wenn der Agent eine Verbindung zu einem Mandanten in stp-cloud.CH herstellen soll, wählen Sie die Umgebung prod-ch. Soll der Agent eine Verbindung zu stp-cloud.DE herstellen, belassen Sie die Voreinstellung prod-de.

3. Geben Sie zunächst den Mandantennamen ein. Dies ist auch die Subdomain des STP Cloud Mandanten der Kanzlei. (Beispiel: für kanzleiname.stp-cloud.de ist der Mandantenname kanzleiname)

4. Geben Sie anschließend die DMS-Datenbank-ID ein. Diese finden Sie im LCAS-Status oder in der Datenbank in der Tabelle tblDatabaseId. Wenn diese ID leer bleibt und mehrere DMS-Server in der Umgebung installiert sind, verbindet sich der Agent mit dem System, das am schnellsten antwortet.

5. Geben Sie dann den Anzeigenamen des Agents an, der später in der App angezeigt wird.

   

6. Konfigurieren Sie anschließend die Verbindungsdaten für den LSB und das STP UserManagement. Dafür muss ein technischer Benutzer für den Agenten im lokalen STP UserManagement („Zentrale Benutzerverwaltung“) angelegt und den Gruppen CloudAccess, ClientProxies und Alle DMS zugewiesen werden. Der technische Benutzer wird dann automatisch in die Cloud synchronisiert. Das Passwort sollte mindestens 15 Zeichen lang sein. Es wird dringend empfohlen, diesem Benutzer eine E-Mail-Adresse zuzuweisen, damit die Authentifizierung im nächsten Schritt erfolgreich ist.

   Der technische Benutzer belegt ebenfalls eine Lizenz in der Lizenzverwaltung für DMS.

   

7. Nun muss die Authentifizierung zur STP Cloud konfiguriert werden. Eine Erklärung zu den einzelnen Optionen finden Sie weiter unten. Es wird dringend empfohlen, hier HTTP auszuwählen und die Cloud-Zugangsdaten des technischen Benutzers für den Agenten einzugeben.

   

   Dem technischen Benutzer für den Agenten muss im Cloud UserManagement ebenfalls ein Passwort zugewiesen werden. Das lokale Passwort wird nicht in die Cloud synchronisiert. Es empfiehlt sich, für den technischen Benutzer in Cloud und On-Premise dasselbe Passwort zu verwenden (mindestens 15 Zeichen). Der Agent-Benutzer benötigt außerdem die Cloud-Gruppe „Documents.Agents“.

8. Geben Sie abschließend den Datenbankserver, die Datenbank und die Datenbank-Anmeldedaten an.

   

9. Sobald alle Felder ausgefüllt sind, wird die eigentliche Installation im letzten Schritt gestartet.

Der Agent wird nun automatisch in das neue Programmverzeichnis (C:\Program Files (x86)\STP AG\STP Documents OnPremise Agent\) kopiert und als Windows-Dienst registriert. Die Datei appsettings.json wird automatisch mit den in der Benutzeroberfläche eingegebenen Werten befüllt. Im Gegensatz zur alten Batch-Installation gibt es keine appsettings..json-Datei mehr.

Sie können jederzeit prüfen, ob der Agent läuft, indem Sie im Browser auf dem System die URL http://localhost:8090 öffnen. Die dort angezeigte Übersicht zeigt auch, ob der Agent erfolgreich mit der STP Cloud und STP.Documents.OnPremise verbunden ist. Wenn der Agent nach 2 Minuten keine erfolgreiche Verbindung zur Cloud und zum DMS aufgebaut hat, empfiehlt es sich, die Logdateien im Programmdatenverzeichnis (C:\ProgramData\STP AG\STP Documents OnPremise Agent\Logs) zu prüfen. Möchten Sie eine Konfigurationsänderung vornehmen, können Sie die appsettings.json im Programmverzeichnis direkt bearbeiten und anschließend den Dienst neu starten. Kann der Browser die oben genannte URL nicht aufrufen, deutet dies darauf hin, dass der Dienst nicht erfolgreich gestartet werden konnte. Die Ursache finden Sie in den Logs.

Beim ersten Start des Agents wird automatisch ein geheimer Schlüssel zur Verschlüsselung generiert und in der Datenbank gespeichert. Der Fingerabdruck des öffentlichen Schlüssels wird im Browser auf der Info-Seite des Agents angezeigt.

Nach erfolgreicher Installation kann das alte Programmverzeichnis der alten Batch-Installation (C:\Program Files\STP AG\STP Document OnPremise Agent) sowie eventuelle Sicherungen dieser Installation entfernt werden. Die neue Installation befindet sich unter "C:\Program Files (x86)\STP AG\STP Documents OnPremise Agent\".

Authentifizierung

Der Agent muss sich an der STP Cloud anmelden, um Anfragen von Apps entgegenzunehmen. Für diese Anmeldung benötigt der Agent ein Access Token. Es werden drei Mechanismen unterstützt, um dieses Access Token zu erhalten.

HTTP

Die empfohlene Methode ist die direkte Kommunikation mit dem STP.Identity UserManagement der STP Cloud. Über HTTPS meldet sich der Agent mit dem standardisierten OpenID Connect (OIDC) Resource Owner Password Grant (Password Flow) in der Cloud an. Dazu sendet er seinen Benutzernamen (in E-Mail-Form) und das Passwort an die Cloud und erhält im Gegenzug ein Access Token. Dafür muss der technische Benutzer des Agents in der Cloud bekannt sein und dort ein Passwort gesetzt haben. Für diese Form der Authentifizierung ist kein LSB mehr erforderlich. Der LSB wird nur noch für die Kommunikation mit STP.Documents.OnPremise benötigt.
In der appsettings.json kann dies auch nachträglich im Bereich AccessCredentials konfiguriert werden. Dazu Provider auf ‘HTTP’ setzen und TenantName, Username und Password ausfüllen. Der Benutzername muss in E-Mail-Form angegeben werden, da das Cloud UserManagement die E-Mail als Login-Namen verwendet.

LSB(S)

Statt sich direkt an der Cloud anzumelden, kann der Agent das Access Token auch indirekt über den LSB und die zugehörige UserManagement.Connector-Infrastruktur erhalten. Auch hier muss der technische Benutzer des Agents in der Cloud existieren, aber es ist nicht erforderlich, dass dort ein Passwort gesetzt wurde. Der Agent muss sich lediglich am lokalen STP UserManagement anmelden können und kann dann über den proprietären Impersonation Grant durch das Vertrauensverhältnis zwischen On-Premise und Cloud ein Access Token erhalten. Dafür muss das lokale STP UserManagement dauerhaft mit der Cloud verbunden sein. Ist diese Verbindung unterbrochen, kann sich der Agent nicht mehr anmelden.
In der appsettings.json kann dies ebenfalls nachträglich im Bereich AccessCredentials konfiguriert werden. Dazu Provider auf ‘LSBS’ setzen und TenantName ausfüllen. Der Mandantenname kann auch weggelassen werden, dann muss Provider auf ‘LSB’ gesetzt werden.

LSBM

Wie bei LSBS kann der Agent das Access Token auch indirekt über LSBM über den LSB erhalten. Der einzige Unterschied ist, dass neuere Versionen von LSB und lokalem STP UserManagement für Multi-Tenant-Umgebungen konfiguriert werden können und dann mit mehreren Cloud-Mandanten verbunden sind. In solchen Umgebungen funktioniert LSBS nicht, genauso wie LSBM in Single-Tenant-Umgebungen nicht funktioniert.
In der appsettings.json kann dies ebenfalls nachträglich im Bereich AccessCredentials konfiguriert werden. Dazu Provider auf ‘LSBM’ setzen und TenantName ausfüllen.

Installation ohne Benutzeroberfläche

$isProjectProperties = '"/qn ' +
'STP_ENVIRONMENT=3 ' +
'STP_TENANT_NAME=... ' +
'STP_DMS_SYSTEM_ID=... ' +
'STP_AGENT_NAME=... ' +
'STP_LSB_HOSTNAME=... ' +
'STP_LSB_PORT=5672 ' +
'STP_LSB_USERNAME=... ' +
'STP_LSB_PASSWORD=... ' +
'STP_ONPREMISE_USER=... ' +
'STP_ONPREMISE_USER_PASSWORD=... ' +
'STP_PROVIDER=2 ' +
'STP_HTTP_USERNAME=... ' +
'STP_HTTP_PASSWORD=... ' +
'STP_DB_SERVER=... ' +
'STP_DB_NAME=... ' +
'STP_DB_USERNAME=... ' +
'STP_DB_PASSWORD=... ' +
'"'

$commandParameters = '/s /v' + $isProjectProperties
Start-Process `"STP.Documents.OnpremiseAgent.exe`" $commandParameters -Wait

Deinstallation

Der „STP Documents On-Premise-Agent“ kann über „Programme und Features“ (oder Software) in der Windows-Systemsteuerung deinstalliert werden. Anschließend sollten Sie prüfen, ob alle Dateien unter „C:Files (x86)AGDocuments OnPremise Agent“ entfernt wurden.