Configure secrets storage using a vault system
Introduction
A vault system allows to store credentials that are required by the Censhare Server in a secure way. The SecretsManger in the Censhare Server then queries the vault system, when credentials are required. The Censhare Server uses these credentials to access Censhare-Server-related services, for example database service or mail service. There are also external services that must be access, for example Amazon Elastic Transcoder.
The following article focuses on the configuration of the Censhare Server in a Censhare Classic setup. In this use case, typically, a vault system already exists. The tasks are then:
Add the required credentials for the Censhare Server to the vault system.
Configure the Censhare Server to access this vault system.
For more information on secret storage and Censhare Server:
For a general overview, see Understand secrets storage.
If you want to use a Secrets file instead of a vault system, see Configure secrets storage using file.
If you are using Censhare Server in Censhare Cloud, see Secrets storage in Censhare Classic and Censhare Cloud.
Set up a vault system to use with Censhare Server
The credentials of the Censhare Server must be stored within a Secrets Engine in the vault system. The Secrets Engine must have the key/value type. The mount point of the Secrets Engine is then configured in the access data for the vault system. Typically, the mountpoint has the name of the Secrets Engine, for example censhare. For more information, see Configure connection to a vault system below.
For each service to access, the SecretsManager assumes that there is a path defined. This path is also called prefix. Below this path, the credentials themselves are stored. Each entry has a key and an associated value.
The following example explains how this can look like for the user ID that is used to login at the database service :
Path: database
Key: user.name
Value: admin
The Censhare Server provides a template for a Secrets file. This template also shows the path and the key/value pairs that are required to access a certain service from within Censhare Server. You find this template here:
../censhare/censhare-Server/app/config/secrets
You must only create entries in your vault system for services that you are using in Censhare Server.
Configure connection to a vault system
The connection to a vault system 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 file itself. You find the file in your censhare-Custom directory tree, for example:
../censhare/censhare-Custom/censhare-Server/app/configTo find the right place in the file, search for censhare secret manager.
The configuration section contains the settings for a vault system and a Secrets file. The following two parameters refer to configuration of a Secrets file and can be ignored for vault system configuration:
censhare.local.secrets
censhare.local.secrets.path
Here is the list of parameters for vault access configuration:
Key | Value(s) | Default value | Enabled | Comment |
|---|---|---|---|---|
censhare.vault.secrets | true/false | false | true | Defines if an external vault system is used |
censhare.vault.address | URL | n/a | true | URL of the external vault system |
censhare.vault.engine.version | Integer | n/a | true | Version of the secretes engine |
censhare.vault.engine | String Example: censhare | n/a | true | Name of the mount point for the secrets engine. The SecretsManager uses a key/value secrets engine. Within the secrets engine, all credentials are stored that are related to the Censhare Server. |
censhare.vault.namespace | NOT USED | n/a | false | Name for the namespace of a tenant. A namespace defines a virtual vault instance. This allows to separate different tenants in one vault system. |
censhare.vault.maxRetries | Integer | 5 | true | Maximal number of retries before the SecretsManager gives up. |
censhare.vault.retryDelayMs | Integer | 1000 | true | Time between two retries in milliseconds |
censhare.vault.token.path | File path Example: “ /opt/corpus/censhare-Secrets/token” | n/a | true | Path of the token to access the vault system. It includes the name of the token file. The SecretsManager uses a token and a certificate to authenticate itself a vault system. |
censhare.vault.certificate.path | File path Example: “ /opt/corpus/censhare-Secrets/certificate” | n/a | true | Path of the certificate to access the vault system. It includes the name of the certificate file. The SecretsManager uses a token and a certificate to access a vault system. |
Apply the new or changed configuration
To apply the new or changed access 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
If you are using a vault system and a Secrets file at the same time, see Use of vault system and Secrets file at the same time for the relevant log entries.
In beginning, the SecretsManager initializes the connection to the external vault system. If this fails, the following message is written into the log:
Vault Service initialization Error: EXCEPTION MESSAGEThe 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 vault system exists. If so, it writes the following message and adds the prefix/path for the related service, for example:
Using vault service access to prefix: databaseIf the SecretManager only wants to access a certain key for a service, the key is also added, for example:
Using vault service access to prefix: database, key: user.nameIf desired entry exists, a success message is written in the log, for example:
Vault Service entry user.name found for prefix : databaserespective:
Vault Service entries found for prefix : databaseIf a vault system exists and the no entries for the service are added, the SecretManager writes the following messsage, for example:
Vault Service entries not found for prefix : databaseIf a failure occurs, it also writes a message. For example, a vault system is configured but cannot be reached. The log entry looks like that:
Vault read failed: ERROR-MESSAGE for remote vault for prefix: databaseERROR-MESSAGE contains information about the specific error.
Clean up your configuration work
After you have successfully applied your configuration to access your vault system, remove the respective credentials entries from the service definitions in the Censhare Admin Client.
WIthout removing entries, your credentials can be as revealed as easy as before!