Configure secrets storage using file

Introduction

The Secrets file allows to store credentials outside of the Censhare Server on the file system of the machine that is running the Censhare Server. The Secrets files is then used by the Censhare Server to find the credentials that are required to access a certain service that is configured in the Censhare Server. This way, credentials cannot be revealed via the Censhare Admin Client.

There is also a higher level of security: Credentials can be also managed via an external vault system. For more information, see:

Structure of the Secrets file

Censhare Server provides a template for a Secrets file. It contains all credentials entries for all services that can be managed by the Secrets Manager of the Censhare Server. The entries marked as comments by a “#” at the beginning of a line.

The template can be found in:

CODE

../censhare/censhare-Server/app/config/secrets

Each credentials entry consists of the following parts:

CODE

PATH.KEY=VALUE

PATH defines the related service, KEY is a key for this service, and VALUE the assigned value.

Example database:

PATH: database
Key: user.name
Entry: database.user.name=xxxxx

Example Keycloak-Client ID:

PATH: keycloak
KEY: authentication.server.client.id
Entry: keycloak.authentication.server.client.id=censhareid

Create a Secrets file

Copy the template file to the place where you want to store the Secrets file, for example:

CODE

/opt/corpus/censhare-Secrets/

For security reasons, the directory should be outside of the file system part for the censhare Server:

For example, if the Censhare Server and related data are stored in this folder:

CODE

/opt/corpus/censhare/

Do not place the Secrets file in this folder or any sub folder.

Configure the Secrets file

By default, all entries related to credentials are marked as comments. After you have created a Secrets file, you must configure the entries for each service that you want to use.

To configure the credentials for a certain service, do the following:

Remove the “#” from the required entries of the desired service, for example:
CODE
```
#database.user.name=xxxx
```
Replace the “xxx” placeholders or respective dummy entries with your credentials values.
Save your changes.

Configure access to the Secrets file

The use of a Secrets file is defined in the launcher.xml file using sysproperty entries.

You can change the entries in Censhare Admin Client in Configuration/Server/Launcher. Scroll down to find the desired entries in the JVM properties section.

You can also change the entries in the launcher.xml itself. You can find the file to change in your censhare-Custom directory tree, for example:

CODE

/opt/corpus/censhare/censhare-Custom/censhare-Server/app/config

To find the right place, search for censhare secret manager.

The configuration contains the settings for a vault system and a Secrets file. For use of a Secrets file configure the following two parameters:

Key

Value(s)

Default value

Enabled

Comment

censhare.local.secrets

true/false

false

true

Defines to use a Secrets file for credentials storage

Set to true if you want to use a Secrets file.

censhare.local.secrets.path

File path

Example: “ /opt/corpus/censhare-Secrets/secrets”

None

true

Defines the path of the Secretsfile. This includes the name of the Secrets file. This parameter is only used if censhare.local.secrets is set to true.

Apply the new or changed configuration

To apply the new or changed configuration, you must restart the Censhare Server. The reason for this is that the launcher.xml file is only read at server start.

Check your log file for success

In beginning, the SecretsManager initializes the connection to the Secrets file. If this fails, the following message is written into the log:

CODE

Local Vault Service initialization Error: EXCEPTION MESSAGE

The log level is set to warning. So, you can filter for WARNING in Kibana via the ets.level field. For more information, see Understand log views.

When the SecretManager in the Censhare Server wants to read credentials, it first checks if a Secrets file exists. If so, it writes the following message and adds the path/prefix for the related service, for example:

CODE

Using local vault service access to prefix: database

If the SecretManager only wants to access a certain key for a service, the key is also added, for example:

CODE

Using local vault service access to prefix: database, key: user.name

If desired the entry exists, a success message is written in the log. For example:

CODE

Local vault Service entry user.name found for prefix : database

If a Secret file exists and the no entries for the service are added, the SecretManager writes the following messsage, for example:

CODE

Local vault service entries not found prefix: database

If a failure occurs, it also writes a message. For example, a Secrets file is configured but does not exist. The log entry looks like that:

CODE

Local Vault Service read failed: ERROR-MESSAGE for local vault for prefix: database

Clean up your configuration work

After you have successfully applied your Secrets file, remove the credentials entries of the services that you configured in the Secrets file from the definitions in the Censhare Admin Client.

WIthout removing entries, your credentials can be as revealed as easy as before!