Storing Datasource Configuration Secrets

Overview

Connector configuration can be accessed from within Seeq via the admin UI or the REST API. This means that if a bad actor were able to acquire admin access to Seeq, then he or she could read a connector configuration and retrieve the credentials for a data service (e.g. a historian). If the bad actor also had network access, he or she could use these credentials to connect to the external data service directly and access data he/she shouldn’t have access to.

To prevent such situations, the connector configuration JSON may optionally contain references to other files where secrets such as passwords and access keys are stored. The documentation for each datasource explicitly lists the fields that support references (with a data type of “String/SecretFile”).

Example using secrets files in a connector configuration

As an example, you can specify the ClientSecret in the Additional Properties for the OAuth 2.0 datasource as a String:

CODE

"ClientSecret" : "mySecret Client secret",

As mentioned, a Seeq admin would be able to see this secret from within Seeq.

To secure this secret, store it instead in a location of your choice (such as C:\ProgramData\Seeq\data\keys\seeq_open_id_client_secret.key) and then reference this file in the configuration:

CODE

"ClientSecret" : "SECRETS_FILE:C:\\ProgramData\\Seeq\\data\\keys\\seeq_open_id_client_secret.key",

The secret can be referenced using absolute paths (as in the example above) or using relative paths to your DATA_DIR:

CODE

"ClientSecret" : "SECRETS_FILE:keys\\seeq_open_id_client_secret.key",

The secrets are stored in plain text within secrets files. However, the secrets file can be locked down (at a OS-filesystem level) so that only some users (and the service user that runs the agent process) can read and/or write to this file. The Windows Service (service user) that runs Seeq (or the Seeq Agent) must have read permissions to the secrets files; otherwise, Seeq will not be able to read the the configuration.

When to extract secrets in separate files

A simple rule is: if a user using Seeq can access an external service (e.g. historian, AD system, etc) using the credentials read from the connector configuration, then these secrets must be extracted to a secrets file and referenced. If the external services can only be accessed by the agent machine and it is guaranteed that other machines cannot access these services directly, then using secrets files is not mandatory to ensure security.

It is recommended to keep all the secrets files in one folder so protection can be set at the folder level.

How to lock down the secrets files

Your enterprise directory account (i.e., your ActiveDirectory account) governs whether or not you can read/write the secrets files. The ActiveDirectory administrator should configure the access to the resources in such a way that only privileged users can access the secrets.

On systems that are not part of a domain the locking down, this must be done at the OS-filesystem level.
On Linux systems this can be done using chown and chmod.
On Windows, it is recommended to use the permission dialog to set the permission on the folder containing the secrets and configure the system to inherit the permission from this folder for all the children folders and files.

Where to place the secrets files

It is recommended to keep all the secrets in a folder in your DATA_DIR. A good location would be the DATA_DIR\\keys folder or a subfolder of it. For example, on Windows the secrets files may be placed in a keys directory as shown:

Although the secrets files store the secret in plain text, security is assured by restricting access to the file at an OS-filesystem level.

Secrets file format

The secrets are stored in plain text in the secrets files. Usually the passwords are placed on the first line of this files. The whole content of the file is used by Seeq as "the secret". Seeq trims the contents of the file before using it (all leading and trailing whitespace is removed, where whitespace is defined as any character whose codepoint is less than or equal to SPACE - U+0020).