# Configuring the available secrets managers

{% hint style="info" %}
**Required global permission:** Manage secrets managers
{% endhint %}

## Supported secrets manager tools and formats <a href="#secrets-manager-platforms-formats" id="secrets-manager-platforms-formats"></a>

Structural currently supports:

* AWS Secrets Manager
* HashiCorp Vault

Structural only supports secrets that store passwords. For AWS Secrets Manager, the passwords must be in one of the following formats:

* String
* JSON

The JSON must contain a map of key-value pairs. It can either:

* Contain a single key for which the value is the password in plaintext.
* Contain a key for which the value is the password in plaintext.

## **Viewing the secrets manager list** <a href="#secrets-manager-list" id="secrets-manager-list"></a>

To display the list of secrets managers, on **Structural Settings** view, click **Secrets Managers**.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2Fg8CM8H28nNgeMlmtHZ7K%2FSecretsManagerTab.png?alt=media&#x26;token=09fded3a-809e-4974-9d91-31ce7c5ae199" alt=""><figcaption><p>Secrets Manager stab on Structural Settings</p></figcaption></figure>

## **Working with secrets managers** <a href="#secrets-manager-config" id="secrets-manager-config"></a>

### **Creating a secrets manager** <a href="#secrets-manager-create" id="secrets-manager-create"></a>

To create a secrets manager:

1. On the **Secrets Managers** tab, click **Add Secrets Manager**.
2. On the **Create Secrets Manager** panel, in the **Name** field, provide a name to use to identify the secrets manager.\
   \
   Secrets manager names must be unique.\
   \
   The name is used in the secrets manager dropdown list on the workspace settings view.
3. From the **Type** dropdown list, select the secrets manager product.\
   \
   Structural currently supports AWS Secrets Manager.
4. Configure the credentials to use to connect to the secrets manager.
5. Click **Save**.

### **Editing an existing secrets manager** <a href="#secrets-manager-edit" id="secrets-manager-edit"></a>

For an existing secrets manager, you can change the name and the credentials configuration.

You cannot change the type.

To edit an existing secrets manager:

1. In the secrets manager list, click the edit icon for the secrets manager.
2. On the **Edit Secrets Manager** panel, update the configuration.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FPbgGzSc5s183fgMJr8VN%2FSecretsManagerEdit.png?alt=media&#x26;token=37b14530-0691-47b6-abe3-bfb6f7a88efb" alt=""><figcaption><p>Edit Secrets Manager panel</p></figcaption></figure>

3. Click **Save**.

### **Deleting a secrets manager** <a href="#secrets-manager-delete" id="secrets-manager-delete"></a>

When you delete a secrets manager, it is removed from the workspace database connections that use it. Structural is no longer able to connect to those databases.

To delete a secrets manager:

1. In the secrets manager list, click the delete icon for the secrets manager.
2. On the confirmation panel, click **Delete**.

## **Providing credentials for AWS Secrets Manager** <a href="#credentials-aws-secrets-manager" id="credentials-aws-secrets-manager"></a>

### Required AWS Secrets Manager permissions <a href="#secrets-manager-aws-permissions" id="secrets-manager-aws-permissions"></a>

The AWS Secrets Manager credentials that you provide must have the following permissions:

* On each secret to use, `secretsmanager:GetSecretValue`&#x20;
* On the encryption key for secrets that are encrypted with a customer managed key (CMK), `kms:Decrypt`

Here is an example policy that grants the required Secrets Manager permissions:

{% code overflow="wrap" %}

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowReadingSecrets",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:us-east-1:111111111111:secret:mySecretNamespace/*"
    }
  ]
}
```

{% endcode %}

### Selecting the source of the credentials <a href="#secrets-manager-aws-credentials-source" id="secrets-manager-aws-credentials-source"></a>

For AWS Secrets Manager, from the **Authentication** dropdown list, select the source of the credentials:

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2F9Gspqr0CF4QhQGDFkOa7%2FSecretsManagerAuthenticationAWS.png?alt=media&#x26;token=7956777d-41f4-448a-9ee3-16781e282361" alt=""><figcaption><p>Authentication options for AWS Secrets Manager</p></figcaption></figure>

* **Environment -** Only available on self-hosted instances.\
  \
  Indicates to use either:
  * The credentials for the AWS Identity and Access Management (IAM) role on the host machine.
  * The credentials set in the following [environment settings](https://docs.tonic.ai/app/admin/environment-variables-setting):
    * `TONIC_AWS_ACCESS_KEY_ID` - An AWS access key that is associated with an IAM user or role
    * `TONIC_AWS_SECRET_ACCESS_KEY` - The secret key that is associated with the access key
    * `TONIC_AWS_REGION` - The AWS Region to send the authentication request to
* **Assume Role -** Indicates to use the specified assumed role.
* **User Credentials -** Indicates to use the provided user credentials.

### **Providing an assumed role** <a href="#credentials-aws-assumed-role" id="credentials-aws-assumed-role"></a>

To provide an assumed role, select **Assume Role**, then:

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2F4XWYZCsGya07eZDjenDO%2FSecretsManagerAuthAWSAssumeRole.png?alt=media&#x26;token=06c6dc9d-7bf2-4651-b2ef-c072b08728e5" alt=""><figcaption><p>Configuration fields for the Assume Role option for AWS Secrets Manager credentials</p></figcaption></figure>

1. In the **Role ARN** field, provide the Amazon Resource Name (ARN) for the role.
2. In the **Session Name** field, provide the role session name.\
   \
   If you do not provide a session name, then Structural automatically generates a default unique value. The generated value begins with `TonicStructural`.
3. In the **Duration (in seconds)** field, provide the maximum length in seconds of the session. \
   \
   The default is 3600, indicating that the session can be active for up to 1 hour.\
   \
   The provided value must be less than the maximum session duration that is allowed for the role.
4. From the **AWS Region** dropdown list, select the AWS Region to send the authentication request to.

Structural generates the external ID that is used in the assume role request. Your role’s trust policy must be configured to condition on your unique external ID.

Here is an example trust policy:

```json
{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Principal": {
      "AWS": "<originating-account-id>"
    },
    "Action": "sts:AssumeRole",
    "Condition": {
      "StringEquals": {
        "sts:ExternalId": "<external-id>"
      }
    }
  }
}
```

### **Providing AWS user credentials** <a href="#credentials-aws-credentials" id="credentials-aws-credentials"></a>

To provide the credentials, select **User Credentials**, then:

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FyJ7lbvinB1EDLmA0fJ65%2FSecretsManagerAuthAWSCredentials.png?alt=media&#x26;token=9fcd2329-47db-498c-a82d-99b9640c48ef" alt=""><figcaption><p>Configuration fields for the User Credentials option for AWS Secrets Manager credentials</p></figcaption></figure>

1. In the **AWS Access Key** field, enter the AWS access key that is associated with an IAM user or role.
2. In the **AWS Secret Key** field, enter the secret key that is associated with the access key.
3. Optional. In the **AWS Session Token** field, provide the session token to use.
4. From the **AWS Region** dropdown list, select the AWS Region to send the authentication request to.

## Configuring a HashiCorp Vault secrets manager

For a HashiCorp Vault secrets manager:

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FiwCzI9S22tbZNaBr0efC%2FSecretsManagerEditHashiCorp.png?alt=media&#x26;token=39123113-519e-46b5-9c60-4ea86df64353" alt=""><figcaption><p>Configuration panel for a HashiCorp Vault secrets manager</p></figcaption></figure>

1. In the **Vault Server** field, provide the server name or IP address where the secrets manager is located.
2. From the **Secrets Engine** dropdown list, select the version of the secrets engine used by the secrets manager.
3. From the **Authentication Method** dropdown list, select how to authenticate to the secrets manager. The options are:
   * **AppRole**
   * **Token**
   * **LDAP**
4. For app role authentication:

   1. In the **Role ID** field, provide the identifier of the application role.
   2. In the **Secret ID** field, provide the secret identifier of the application role.

   On a self-hosted instance, if you do not provide a role identifier and secret identifier, then Structural uses the values of the [environment settings](https://docs.tonic.ai/app/admin/environment-variables-setting) `TONIC_SECRET_MANAGERS_HASHICORP_VAULT_APPROLE_ROLE_ID` and `TONIC_SECRET_MANAGERS_HASHICORP_VAULT_APPROLE_SECRET_ID`.
5. For token authentication, in the **Token** field, provide the authentication token to use.\
   \
   On a self-hosted instance, if you do not provide a token, Structural uses the value of the [environment setting](https://docs.tonic.ai/app/admin/environment-variables-setting) `TONIC_SECRET_MANAGERS_HASHICORP_VAULT_TOKEN` to authenticate.
6. For LDAP authentication:

   1. In the **Username** field, provide the LDAP username.
   2. In the **Password** field, provide the password for the LDAP user.

   On a self-hosted instance, if you do not provide a username and password, then Structural uses the values of the [environment settings](https://docs.tonic.ai/app/admin/environment-variables-setting) `TONIC_SECRET_MANAGERS_HASHICORP_VAULT_LDAP_USERNAME` and `TONIC_SECRET_MANAGERS_HASHICORP_VAULT_LDAP_PASSWORD`.
7. If the authentication method is enabled in a specific namespace, then in the **Namespace** field, provide the namespace.
8. If the selected authentication method does not use the default mount path, then in the **Mount path** field, provide the mount path.

## Configuring a CyberArk Central Credential Provider secrets manager

For a CyberArk secrets manager:

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2F3xUWIPbbXGCHEZZYuV6X%2FSecretsManagerEditCyberArk.png?alt=media&#x26;token=0f81de67-b8b0-4d8d-9eb1-6c5d608a4088" alt=""><figcaption><p>Configuration panel for a CyberArk Credential Provider secrets manager</p></figcaption></figure>

1. In the **CyberArk Server** field, provide the server name or IP address where the secrets manager is located.
2. In the **CyberArk Port** field, provide the port to use to connect to the secrets manager.
3. In the **CyberArk Application ID** field, provide the identifier of the CyberArk application that contains the secrets manager.
4. In the **CyberArk Safe** field, provide the name of the CyberArk safe that contains the secrets.
5. Optional. In the **CyberArk Folder** field, provide the name of the folder within the safe that contains the secrets.\
   \
   If you do not specify a folder here or in the workspace configuration, the folder defaults to `Root`.\
   \
   To specify a folder path, use `Root` followed by the rest of the path, with each path component separated by backslashes. For example: `Root\OS\Linux`.

By default, Structural uses the application identifier to authenticate to CyberArk.

You can instead use a CyberArk authentication certificate.

When you use a certificate, then by default, during authentication, Structural validates the certificate that the server sends. You might need to install a root certificate on the Structural web server and workers. Instead, to bypass the validation, set the [environment setting](https://docs.tonic.ai/app/admin/environment-variables-setting) `TONIC_SECRET_MANAGERS_CYBER_ARK_CCP_VERIFY_SERVER_CERTIFICATE`  to `false`.

To configure the CyberArk authentication certificate:

1. Click **Certificate**.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FW395rLAxcpVySY5FWTFQ%2FSecretsManagerEditCyberArkCertificate.png?alt=media&#x26;token=e84a99c5-2560-4669-b679-8fe29bd7f37a" alt=""><figcaption><p>Configuration for a CyberArk authentication certificate</p></figcaption></figure>

2. Under **CyberArk Authentication Certificate**, to search for and select the certificate file, click **Browse**.\
   \
   The certificate must be either .pfx or .p12.
3. In the **CyberArk Certificate Password** field, provide the password that is associated with the certificate.

## Testing a secrets manager configuration

From the configuration panel, you can test whether Structural can use the configured credentials to connect to the secrets manager and retrieve a specific secret.

### Running the configuration test

To test a secrets manager configuration:

1. Click **Test Secrets Manager**.
2. On the **Test Secrets Manager** panel, in the **Secret Name** field, provide the name of the secret.
3. If needed for the secrets manager type, provide any other information that is needed for the connection.
4. Click **Run Test**.

### Additional test information for HashiCorp Vault

For a HashiCorp Vault secrets manager, in addition to the secret name, you can provide the following if applicable:

* **Namespace -** If the secret is in a specific namespace, the name of the namespace.
* **Mount Path -** If the secrets engine does not use the default mount path, the mount path to use.

### **Additional test information for CyberArk Central Credential Provider**

For a CyberArk Central Credential Provider secrets manager, in addition to the secret name, you can optionally provide:

* **CyberArk Safe -** The name of the CyberArk safe that contains the secrets manager.
* **CyberArk Folder** - The name of the folder within the safe that contains the secrets manager.

If you do not provide these values, they fall back to the values that are configured for the secrets manager.