Configure Your HashiCorp Vault

The following steps use the HashiCorp Vault user interface (UI) to guide you through the configuration of your HashiCorp Vault instance.

These configurations are mandatory for on premise Clarity LIMS deployments. For hosted deployments, this configuration is completed by Illumina.

Detailed information and instructions for HashiCorp Vault are available on the HashiCorp website: www.hashicorp.com.

Pre-requisites

1. You are planning to install Clarity LIMS v6.0.0 and newer.

2. You have installed the latest version of either HashiCorp Vault Open Source or Enterprise.

3. You have read the Getting Started tutorials for Vault on the HashiCorp website and/or possess a basic knowledge of HashiCorp Vault.

4. You have system administrator permissions to perform the necessary operations to your HashiCorp Vault instance.

5. You have allowed the necessary port 443 from the Clarity LIMS instance to your HashiCorp Vault instance.

6. You have access to all the passwords required to be configured in your HashiCorp Vault instance.

Configuration

Enable a new KV Secret Engine

To enable a new KV Secret Engine, refer to the Versioned Key/Value Secrets Engine tutorial provided on the HashiCorp Vault website.

Configuring Secret Engine

The following table lists the secrets required for Clarity LIMS. To use the paths shown in the table, replace $host with your fully qualified domain name (FQDN).

Path	Purpose
$host/clarity/app.ftp.password	Password for GLSFTP user on the Clarity LIMS instance.
$host/clarity/app.rabbitmq.password	Password for RabbitMQ admin on the Clarity LIMS instance.
$host/clarity/db.clarity.password	Password for the configured Clarity LIMS database user
$host/clarity/db.lablink.password	Password for the configured LabLink database user.
$host/clarity/db.tenant.password	Password for the configured Tenant Lookup DB database user.
$host/clarity/app.ldap.managerPass	[Optional] Password for the User DN configured for Clarity LIMS LDAP integration.
$host/integration/apiusers/apiuser	Password for the apiuser user account that is used by Automation Worker to authenticate with Clarity LIMS API. If you have configured a different user account, create it under $host/integration/apiusers/$username
global/platform.clientId	[Optional] Required for Clarity LIMS Platform Auth integration.

When configuration is complete, these secrets are listed in the Vault user interface.

Authentication Methods

AppRole

AppRole is the recommended authentication method to use with the Clarity LIMS Secret Utility tool.

1. To enable the AppRole authentication method, refer to the AppRole Pull Authentication tutorial provided on the HashiCorp Vault website.

2. When AppRole is enabled, create an AppRole with the appropriate Access Control List (ACL) policy (see the following section).

3. Make a note of the Role ID and Secret ID. You need these IDs when configuring Secret Utility.

Secret Utility does not manage your Role ID and Secret ID for you (eg, renewing, revoking, and so on). It accepts the Role ID and Secret ID as-is, and attempts to authenticate with Vault.

Token

Alternatively, the Clarity LIMS Secret Utility tool also works with the token authentication method.

To learn more about tokens, see the Tokens documentation on the HashiCorp Vault website.

Secret Utility does not manage your tokens for you (eg, renewing, revoking, and so on). It accepts the token as-is, and attempts to authenticate with Vault.

Authentication ACL Policies

After enabling the AppRole authentication method, create ACL policies to access the Secret Engine.

IMPORTANT: Replace "claritylims" with your Secret Engine path.

ACL Policies

# For clarity instance to read from hashicorp vault
path "claritylims/data/+/clarity/*"
{
  capabilities = ["read"]
}
# For integration to write to hashicorp vault
path "claritylims/data/+/integration/*"
{
  capabilities = ["read","create","update"]
}
# For listing and deleting metadata of integration keys
path "claritylims/metadata/+/integration/*"{
  capabilities = ["list","delete"]
}
# For global values
path "claritylims/data/global/*"
{
   capabilities = ["read"]
}

You might need to update or create additional ACL policies for your System Administrator to rotate the credentials, when required.

To create the ACL policy, refer to the Vault Policies tutorial provided on the HashiCorp Vault website.

Verification

1. SSH into the Clarity LIMS instance.

2. After installing Clarity LIMS and configuring Secret Utility using the instructions provided in Guide to Secret Management, run the command to read an existing password/secret from HashiCorp Vault.