Guide to Secret Management

The Vault ACLs control three main paths: Clarity, Integration, and Ops. If there is an attempt to write into a read-only path, secretutil.jar returns an error.

Clarity (read only)

• Stores all passwords related to Clarity LIMS. The secrets/passwords are encrypted with CLARITYSECRET_ENCRYPTION_KEY env variable. See #configuration-script.

Integration (read write)

• Stores all integration-related passwords and allows read and write access.

• apiusers

  • Stores passwords that are used by packages and applications for API authentication (eg, the apiuser password).

  • Username is case sensitive.

  • For example, retrieve apiuser password from integration/apiusers/apiuser.

• external.file.stores

  • Stores password of external file stores used by Clarity LIMS.

  • External file store is optional to the Clarity LIMS system.

  • For example, retrieve file store password from integration/external.file.stores/.password.

Ops

• Stores secrets related to operations.

  • For Illumina cloud hosted deployments, Illumina manages this path.

  • This path is optional for on-premise customers.

Using Secret Utility

The following command creates a new password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-gh] [-n=<namespace>] [-u=<newValue>] <key>

• When creating a new password for integration, specify the -n= integration option.

• Make sure that the key uses a forward slash for nested secrets. For example, apiusers/apiuser

• The same command is used for updating an existing password and creating a new password. Read the key you are planning to create to check whether it is an existing password.

Using Vault UI

1. Log in to the Vault UI.

2. Select the Key Value (KV) secret engine with the path instances.

3. Look for the FQDN instance that you want to create the password for.

4. Select the path where you want to create the new password, ie, clarity/integration/ops.

5. Select Create Secret +.

6. Under Path for this secret, enter the path for the new password, eg, app.ldap.managerPass.

7. Under Version data:

   1. Enter 'value' into the key field.

   2. Enter the new password into the value field.

8. Select Save.

Using Secret Utility

Run the following command to create a new password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar <key>

Using Vault UI

1. Log in to the Vault UI.

2. Select the KV secret engine with the path instances.

3. Look for the FQDN instance that you want to create the password for.

4. Select the path where the existing password is located, ie, clarity/integration/ops.

5. Click into the secret and view the password by selecting the peek icon.

NOTE: Global values can be updated through Vault UI only.

Using Secret Utility

Run the following command to update an existing password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-gh] [-n=<namespace>] [-u=<newValue>] <key>

Using Vault UI

1. Log in to the Vault UI.

2. Select the KV secret engine with the path instances.

3. Look for the FQDN instance that you want to create the password for.

4. Select the path where the existing password is located, ie, clarity/integration/ops.

5. Select into the secret.

6. Select Create new version +.

7. Under Version Data, enter the new password.

8. Select Save.

NOTE: Confirm with the Illumina Support team before deleting passwords and secrets.

Using Secret Utility

Secret Utility does not support permanent deletion of a key by design.

Using Vault UI

1. Log in to the Vault UI.

2. Select the KV secret engine with the path instances.

3. Look for the FQDN instance that you want to create the password for.

4. Select the path, ie, clarity/integration/ops, to the location of the existing password.

5. Select into the secret.

6. Select Delete secret.

Run the following command to create a new password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-gh] [-n=<namespace>] [-u=<newValue>] <key>

• If you are creating a new password for integration, specify the -n=integration option.

• The same command is used for updating an existing password and creating a new password. Read the key you are planning to create to check whether it is an existing password.

Run the following command to read an existing password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar <key>

NOTE: Global values can only be updated through secret utility in File Mode.

Run the following command to update an existing password:

java -jar /opt/gls/clarity/tools/secretutil/secretutil.jar [-gh] [-n=<namespace>] [-u=<newValue>] <key>

NOTE: Confirm with the Illumina Support team before deleting passwords and secrets.

By design, Secret Utility does not support permanent deletion of a key. As an alternative, you can run the following steps.

1. Open the secrets.properties file with an editor, eg, vim.

2. Remove the key from the file and save the file.