Installation OnPremise Agent

Installation

Der STP.Documents On-premise-Agent verbindet den STP.Documents-Dienst in der STP Cloud mit dem STP.Documents.OnPremise-System auf dem Kanzleiserver. Die Installation per Installer ist einfacher also die alte Batch-Installation. Der Installateur wird über eine grafische Benutzeroberfläche durch die Installation geführt.

  1. Starten des Setups (STP.Documents.OnpremiseAgent (...).exe) in einem lokalen Verzeichnis (nicht von einem Netzlaufwerk!) und, im Falle einer Migration, öffnen der gesicherten Konfigurationsdatei appsettings.<MACHINE-NAME>.json.

  2. Wenn der Agent sich mit einem Tenant in stp-cloud.CH verbinden soll, kann die Umgebung prod-ch ausgewählt werden. Wenn der Agent sich mit stp-cloud.DE verbinden soll, kann die Vorbelegung auf prod-de bleiben.

  3. Zuerst muss der Tenantname angegeben werden. Das ist gleichzeitig die Subdomain des STP Cloud Tenants der Kanzlei. (Beispiel: bei kanzleiname.stp-cloud.de lautet der Tenantname kanzleiname)

  4. Dann sollte die DMS-Database-ID angegeben werden. Sie wird im LCAS-Status oder in der Datenbank in der Tabelle tblDatabaseId angezeigt. Wenn diese ID leer bleibt und in der Umgebung mehrere DMS-Server installiert sind, verbindet sich der Agent nur mit dem am schnellsten antwortenden System.

  5. Dann muss der Anzeigename des Agenten angegeben werden, der später in der App angezeigt werden soll.

  6. Als nächstes müssen die Verbindungsinformationen für den LSB und das STP UserManagement konfiguriert werden. Dafür muss ein technischer Benutzer für den Agenten im On-premises 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 mindestend 15 Zeichen lang sein. Diesem Benutzer sollte auch dringend eine E-Mail-Adresse zugewiesen werden, sodass die Authentifizierung im nächsten Schritt gelingt.

    Der Technische Benutzer belegt auch eine Lizenz in der Lizenzverwaltung für DMS

  7. Anschließend muss die Authentifizierung gegenüber der STP Cloud eingestellt werden. Eine Erklärung der einzelnen Optionen findet sich unten. Es wird dringend empfohlen, hier HTTP auszuwählen und die Cloud-Zugangsdaten des technischen Benutzers für den Agenten einzutragen.

    Dem technischen Benutzer für den Agenten muss dazu im Cloud UserManagement ein Passwort vergeben werden. Das On-premise Passwort wird nämlich nicht in die Cloud synchronisiert. Es ist empfehlenswert dem technischen Benutzer in der Cloud und On-premise das gleiche Passwort zu geben (mindestens 15 Zeichen lang). Der Agent-Benutzer benötigt außerdem die Cloud-Gruppe “Documents.Agents”.

  8. Abschließend muss noch der Datenbankserver, die Datenbank und der Datenbank-Login angegeben werden.

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

Der Agent wird jetzt automatisch in das neue Prgrammverzeichnis (C:\Program Files (x86)\STP AG\STP Documents OnPremise Agent\) kopiert und als Windows-Dienst registriert. Dabei wird die Datei appsettings.json automatisiert mit den in die Benutzeroberfläche eingetragenen Werten ausgefüllt. Im Gegensatz zur alten Batch-Installation gibt es keine appsettings.<MACHINE-NAME>.json-Datei mehr.

Ob der Agent läuft, kann jederzeit überprüft werden, indem auf dem System die URL http://localhost:8090 im Browser geöffnet wird. In der dortigen Übersicht wird auch angezeigt, ob der Agent sich erfolgreich mit der STP Cloud und dem STP.Documents.OnPremise verbunden hat. Sollte der Agent sich nach 2 Minuten nicht erfolgreich mit der Cloud und DMS verbunden haben, empfiehlt sich ein Blick in die Log-Dateien im Programmdatenverzeichnis (C:\ProgramData\STP AG\STP Documents OnPremise Agent\Logs). Wenn eine Konfigurationsänderung vorgenommen werden soll, kann die appsettings.json im Programmverzeichnis direkt geändert und der Dienst anschließend neugestartet werden. Sollte der Browser nicht zu der eben genannten URL navigieren können, ist das ein Indikator dafür, dass der Dienst nicht erfolgreich starten konnte. Die Ursache hierfür wird in den Logs stehen.

Wenn der Agent das erste Mal gestartet wird, wird automatisch ein geheimer Schlüssel für die Verschlüsselung generiert und in der Datenbank hinterlegt. Der Fingerprint des öffentlichen Schlüssels wird im Browser auf der Info-Seite des Agenten angezeigt.

Nach erfolgreicher Installation kann das alte Programmverzeichnis der alten Batch-Installation (C:\Program Files\STP AG\STP Document OnPremise Agent) und mögliche Sicherheitskopien aus 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 in der STP Cloud anmelden, um Anfragen von Apps entgegen nehmen zu können. Für diese Anmeldung benötigt der Agent ein Access Token. Es werden drei Mechanismen unterstützt, wie er sich dieses Access Token beschaffen kann.

HTTP

Der empfohlene Weg ist die direkte Kommunikation mit dem STP.Identity UserManagement der STP Cloud. Über HTTPS meldet sich der Agent in der Cloud über den standardisierten OpenID Connect (OIDC) Resource Owner Password Grant (Password Flow) an. Dazu schickt er seinen Benutzernamen (in E-Mail-Form) und Passwort in die Cloud und erhält ein Access Token als Antwort zurück. Hierfür muss der technische Benutzer des Agenten in der Cloud bekannt sein und sich in der Cloud ein Passwort vergeben haben. Für diese Form der Authentifizierung ist also kein LSB mehr nötig. Der LSB ist nur noch für die Kommunikation mit STP.Documents.OnPremise erforderlich.  In der Datei appsettings.json kann dies in dem Bereich AccessCredentials auch nachträglich konfiguriert werden. Dazu muss Provider auf 'HTTP' gesetzt und TenantName, Username sowie Password ausgefüllt werden. Der Username muss dabei in E-Mail-Form angegeben werden, denn das Cloud UserManagement verwendet die E-Mail als Login-Namen.

LSB(S)

Statt sich direkt in der Cloud anzumelden, kann der Agent sich auch indirekt über den LSB und die damit verbundene UserManagement.Connector-Infrasturktur ein Access Token holen lassen. Auch hier muss der technische Benutzer des Agenten in der Cloud vorhanden sein, allerdings ist nicht erforderlich, dass er sich in der Cloud ein Passwort gegeben hat. Der Agent muss sich lediglich am On-premises STP UserManagement anmelden können und kann dann über die Vertrauensstellung zwischen On-Premises und Cloud ein Access Token über den proprietären Impersonation Grant beziehen. Dafür muss das On-premises STP UserManagement kontinuierlich mit der Cloud verbunden sein. Ist diese Verbindung gestört, kann auch der Agent sich nicht mehr anmelden.
In der Datei appsettings.json kann dies in dem Bereich AccessCredentials auch nachträglich konfiguriert werden. Dazu muss Provider auf 'LSBS' gesetzt und TenantName ausgefüllt werden. Der Tenantname kann auch weggelassen werden, allerdings muss Provider dann auf 'LSB' gesetzt werden.

LSBM

Genau wie bei LSBS kann der Agent sich auch mit LSBM über den LSB indirekt ein Access Token holen lassen. Der Unterschied besteht lediglich darin, dass neuere Versionen von LSB und On-premises STP UserManagement für Multi-Tenant-Umgebungen konfiguriert werden können und dann mit mehreren Cloud-Tenants verbunden sind. In solchen Umgebungen funktioniert LSBS nicht, genauso wenig wie LSBM in Single-Tenant-Umgebungen funktionieren würde.  In der Datei appsettings.json kann dies in dem Bereich AccessCredentials auch nachträglich konfiguriert werden. Dazu muss Provider auf 'LSBM' gesetzt und TenantName ausgefüllt werden.

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

Aktualisierung auf eine neue Version

Ab Version 1.5.19 ist die Aktualisierung des Agenten im Prinzip "Weiter, weiter, fertigstellen". Der Installer darf hierzu nicht von einem Netzlaufwerk gestartet werden.

Aufgrund eines Fehlers im Installer der Version 1.4.166 ist eine Aktualisierung eben dieser Version leider nicht direkt möglich. Daher muss die Version 1.4.166 zuerst deinstalliert werden, bevor die neuere Version installiert werden kan.

  1. Zuerst muss die Datei "appsettings.json" aus dem Programmverzeichnis unter "C:\Program Files (x86)\STP AG\STP Documents OnPremise Agent" gesichert werden. Sie enhält alle Konfigurationseinstellungen.
  2. Über "Programme und Funktionen" (bzw. Software) in der Windows-Systemsteuerung muss dann der "STP Documents On-Premise-Agent" deinstalliert werden.
  3. Dann kann der neue Agent (ab 1.5.19) mit dem neuen Installer installiert werden. Dabei können entwedet die Konfigurationswerte aus der gesicherten "appsettings.json" verwendet werden, oder es werden beliebige Konfigurationswerte verwendet und nach Abschluss der Installation wird die gesicherte "appsettings.json" wiederhergestellt.

Deinstallation

Über "Programme und Funktionen" (bzw. Software) in der Windows-Systemsteuerung kann der "STP Documents On-Premise-Agent" deinstalliert werden. Danach sollte noch überprüft werden, ob wirklich alle Dateien unter "C:\Program Files (x86)\STP AG\STP Documents OnPremise Agent" entfernt wurden.