Configuring the available secrets managers

Required global permission: Manage secrets managers

Supported secrets manager tools and formats

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

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

Secrets Manager stab on Structural Settings

Working with secrets managers

Creating a secrets manager

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

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.

Edit Secrets Manager panel

1. Click Save.

Deleting a secrets manager

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

Required AWS Secrets Manager permissions

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

• On each secret to use, secretsmanager:GetSecretValue

• 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:

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

Selecting the source of the credentials

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

Authentication options for AWS Secrets Manager

• 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:

    • 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

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

Configuration fields for the Assume Role option for AWS Secrets Manager credentials

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:

{
  "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

To provide the credentials, select User Credentials, then:

Configuration fields for the User Credentials option for AWS Secrets Manager credentials

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:

Configuration panel for a HashiCorp Vault secrets manager

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 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 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 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.

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.