Enabling the System User Login for Microservices

This guide is applies to core service version >=6.12 and dmssidecar service version >=6.0.0

In the past there was the need to configure a technical user that was used by every microservice to access the core-serivce, if it was not possible to provide an end user authorization.  For the technical user the system maintainer had to provide all access rights for all object types and had to set all functional rights. If the maintainer failed or forgot to do so, it was possible to get an erroneous system with inconsistent data.

It is now possible to use the core-service internal system user for remote login by the the dmssidecar service. By comparisson with a technical user, this system user automatically has all object type rights and all functional rights. To secure this access to the core-service with this extended priviliges, these measures apply:

1. The core-service and the dmssidecar service must use a shared secret API key. This key must be configured for both services.
2. By default, the core-service accepts system user logins only from the dmssidecar service host. Access from other remote hosts is denied. This behaviour can be controlled by a local preference: com.os.ecm.messaging.LocalSidecarPreferences.CheckSystemUserAccessFromSidecarOnly. The default is: true.
   The remote dmssidecar service host is checked against the host of the configured sidecar url, set during the setup or by com.os.ecm.messaging.LocalSidecarPreferences.SidecarUrl.

For new installations of the core-service and the microservices, the shared API key configuration is handled by the setup. The core-service installation program will generate a key, that can later be used for the service-manager setup. For existing system that are updated, the use of the system user must be configured manually as described below. 

Configuring a System User API Key in the Core Service

1. Stop the core-service.
2. Start <core-service>\bin\yuuvis_rad_core-servicew.exe. (The name may vary depinding on the initial installation version and the service name. It is always a executable ending with 'w.exe'.)
3. Select the tab "Java".
4. Under "Java Options" add this entry:

   -Dcom.os.ecm.systemuserkey=<SHARED_API_KEY>

   Replace <SHARED_API_KEY> with the actual key of your choice. There are no restrictions for the length or content of the api key. It is more than suffiicient to use a 32 character guid, for example as created here: https://www.guidgenerator.com/online-guid-generator.aspx
   
5. Save the changes by pressing ok.
6. Start the core-service.

After startup you can check, if the system user api key is set by opening the monitor status page (with adminstrator rights): http://<core-service-ip>:8080/rest-ws/service/management/settings. Search for "systemuserkey" in the resulting page.

Configuring the System User API Key for the dmssidecar Service

1. Stop the service-manager service.
2. Open the file <service-manager>\config\application-red.yml
3. Add the line 

   enaio.dms.apikey: <SHARED_API_KEY>

   Replace <SHARED_API_KEY> with the same key used for the core-service.

4. Remove the existing lines:
   enaio.dms.username, enaio.dms.password, enaio.server.username, enaio.server.password

5. Restart the service-manager service.