Configuring secrets managers for database connections

Your organization might use a secrets manager to secure credentials, including database connection credentials.

For data connector credentials, you can configure a set of available secrets managers. In the workspace configuration, users can then select a secret name from a secrets manager.

Supported secrets manager tools and formats

Structural currently supports AWS Secrets Manager.

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 that is labeled either password or pw, 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 Manager.

Working with secrets managers

Creating a secrets manager

To create a secrets manager:

1. On the Secrets Manager 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.

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:

• secretsmanager:ListSecrets

• 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": "AllowSecretsManagerActions",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:ListSecrets"
      ],
      "Resource": "arn:aws:secretsmanager:us-east-1:111111111111:secret:mySecretNamespace/*"
    }
  ]
}

Selecting the source of the credentials

For AWS Secrets Manager, under Authentication, select the source of the credentials:

• 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

• Assumed 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, click Assume Role, then:

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, click User Credentials, then:

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.