OnPremise Agent Installation

Update to a New Version

Starting from version 1.5.19, updating the agent is essentially a “Next, next, finish” process. The installer must not be started from a network drive.

Due to a bug in the installer of version 1.13.*, it is unfortunately not possible to update to this version directly. Therefore, the older version must first be uninstalled before the newer version can be installed.

  1. First, back up the appsettings.json file from the program directory at C:\Program Files (x86)\STP AG\STP Documents OnPremise Agent. It contains all configuration settings.
  2. Then, use “Programs and Features” (or Software) in the Windows Control Panel to uninstall the “STP Documents On-Premise-Agent”.
  3. After that, the new agent can be installed. You can either use the configuration values from the backed-up appsettings.json or use any configuration values during installation and restore the backed-up appsettings.json after the installation is complete.

Installation

The STP.Documents On-premise Agent connects the STP.Documents service in the STP Cloud with the STP.Documents.OnPremise system on the law firm’s server. Installation via the installer is simpler than the old batch installation. The installer guides you through the installation process using a graphical user interface.

  1. Start the setup (STP.Documents.OnpremiseAgent (...).exe) in a local directory (not from a network drive!). In case of a migration, open the saved configuration file appsettings..json.

  2. If the agent should connect to a tenant in stp-cloud.CH, select the environment prod-ch. If the agent should connect to stp-cloud.DE, keep the default prod-de.

  3. First, enter the tenant name. This is also the subdomain of the STP Cloud tenant for the law firm. (Example: for kanzleiname.stp-cloud.de, the tenant name is kanzleiname)

  4. Next, enter the DMS Database ID. This can be found in the LCAS status or in the database in the table tblDatabaseId. If this ID is left empty and multiple DMS servers are installed in the environment, the agent will connect to the system that responds the fastest.

  5. Then, specify the display name of the agent, which will be shown later in the app.

  6. Next, configure the connection information for the LSB and the STP UserManagement. For this, a technical user for the agent must be created in the on-premises STP UserManagement (“Central User Management”) and assigned to the groups CloudAccess, ClientProxies, and Alle DMS. The technical user will then be automatically synchronized to the cloud. The password should be at least 15 characters long. It is strongly recommended to assign an email address to this user so that authentication in the next step succeeds.

    The technical user also occupies a license in the license management for DMS.

  7. Then, authentication to the STP Cloud must be configured. An explanation of the individual options can be found below. It is strongly recommended to select HTTP here and enter the cloud credentials of the technical user for the agent.

    The technical user for the agent must also be assigned a password in the Cloud UserManagement. The on-premise password is not synchronized to the cloud. It is recommended to use the same password for the technical user in both the cloud and on-premise (at least 15 characters long). The agent user also needs the cloud group “Documents.Agents”.

  8. Finally, specify the database server, the database, and the database login.

  9. After all fields have been filled in, the actual installation is started in the final step.

The agent is now automatically copied into the new program directory (C:\Program Files (x86)\STP AG\STP Documents OnPremise Agent\) and registered as a Windows service. The appsettings.json file is automatically filled with the values entered in the user interface. Unlike the old batch installation, there is no longer an appsettings..json file.

You can check at any time whether the agent is running by opening the URL http://localhost:8090 in a browser on the system. The overview there also shows whether the agent has successfully connected to the STP Cloud and STP.Documents.OnPremise. If the agent has not successfully connected to the cloud and DMS after 2 minutes, it is recommended to check the log files in the program data directory (C:\ProgramData\STP AG\STP Documents OnPremise Agent\Logs). If you want to make a configuration change, you can edit the appsettings.json in the program directory directly and then restart the service. If the browser cannot navigate to the above-mentioned URL, this indicates that the service could not start successfully. The cause will be found in the logs.

When the agent is started for the first time, a secret key for encryption is automatically generated and stored in the database. The fingerprint of the public key is displayed in the browser on the agent’s info page.

After successful installation, the old program directory of the old batch installation (C:\Program Files\STP AG\STP Document OnPremise Agent) and any backups from this installation can be removed. The new installation is located under "C:\Program Files (x86)\STP AG\STP Documents OnPremise Agent\".

Authentication

The agent must log in to the STP Cloud to accept requests from apps. For this login, the agent needs an access token. Three mechanisms are supported for obtaining this access token.

HTTP

The recommended way is direct communication with the STP.Identity UserManagement of the STP Cloud. Via HTTPS, the agent logs in to the cloud using the standardized OpenID Connect (OIDC) Resource Owner Password Grant (Password Flow). To do this, it sends its username (in email form) and password to the cloud and receives an access token in response. For this, the technical user of the agent must be known in the cloud and must have set a password in the cloud. For this form of authentication, no LSB is required anymore. The LSB is only needed for communication with STP.Documents.OnPremise.
In the appsettings.json file, this can also be configured later in the AccessCredentials section. To do this, set Provider to ‘HTTP’ and fill in TenantName, Username, and Password. The username must be specified in email form, as the Cloud UserManagement uses the email as the login name.

LSB(S)

Instead of logging in directly to the cloud, the agent can also indirectly obtain an access token via the LSB and the associated UserManagement.Connector infrastructure. Here too, the technical user of the agent must exist in the cloud, but it is not necessary for them to have set a password in the cloud. The agent only needs to be able to log in to the on-premises STP UserManagement and can then obtain an access token via the proprietary Impersonation Grant through the trust relationship between on-premises and cloud. For this, the on-premises STP UserManagement must be continuously connected to the cloud. If this connection is disrupted, the agent can no longer log in.
In the appsettings.json file, this can also be configured later in the AccessCredentials section. To do this, set Provider to ‘LSBS’ and fill in TenantName. The tenant name can also be omitted, but then Provider must be set to ‘LSB’.

LSBM

Just like with LSBS, the agent can also obtain an access token indirectly via LSBM through the LSB. The only difference is that newer versions of LSB and on-premises STP UserManagement can be configured for multi-tenant environments and are then connected to multiple cloud tenants. In such environments, LSBS does not work, just as LSBM would not work in single-tenant environments.
In the appsettings.json file, this can also be configured later in the AccessCredentials section. To do this, set Provider to ‘LSBM’ and fill in TenantName.

Installation without User Interface

$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

Uninstallation

The “STP Documents On-Premise-Agent” can be uninstalled via “Programs and Features” (or Software) in the Windows Control Panel. Afterwards, you should check whether all files under “C:Files (x86)AGDocuments OnPremise Agent” have been removed.

Related to