AWS Secrets Manager

Secret store integrations allow you to use your existing third-party secret stores with StrongDM. Your credentials are stored in a tool that is controlled by you, and those credentials are never transmitted to StrongDM in any form. If you would like to learn more about how this integration works and why you might wish to use it, please read the Secret Stores Reference.

This guide will walk you through how to integrate AWS Secrets Manager with StrongDM and how to use it to connect to resources.

Set up AWS Secrets Manager

To get started with AWS Secrets Manager, store credentials to some of your resources in it and note the correct paths to those credentials. Then, set up your Relay server to be able to authorize to the Secrets Manager with an access key.

Set up your credentials

Set up your credentials in AWS Secrets Manager. This should be as simple as heading to Secrets Manager in the AWS Management Console and following the prompts to create your first secret.

You may choose to organize your credentials by slug (e.g., postgres) or namespace/path (e.g., /credentials/databases/postgres). Either way, when asked for the path to your secret later, this name is that path.

Authenticate with AWS

You can authenticate your gateway server with AWS in several ways.

Option 1: Access keys via environment variables

1. Get an access key for AWS and set the necessary environment variables on your Relay server (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY).

2. Open the environment file for editing. The default location is /etc/sysconfig/sdm-proxy for gateways and relays, or /etc/sysconfig/sdm-worker for proxy clusters.

3. Add the following lines, substituting your ID and key:

   AWS_ACCESS_KEY_ID=aswf234rt4rsag4t3g
   AWS_SECRET_ACCESS_KEY=23452321h2893hf2ioufh2938229fh2oufgh23890fh29fh23bif2f0928hf02f3n2bf290fn9230f

4. Restart the service. If your system uses systemd, the command is sudo systemctl restart sdm-proxy for gateways and relays, or sudo systemctl restart sdm-worker for proxy clusters.

Option 2: IAM via EC2 role

If you intend to use an EC2 instance that is in the same AWS account as your Secrets Manager, you can follow these instructions:

1. In your AWS Management Console, navigate to IAM, click on Role, and click on Create Role.

2. Select EC2 for Service.

3. In the policy, select SecretsManagerReadWrite, and click Next.

4. Add the role name and description, and then go to EC2 and click on Instances.

5. Select the instance that houses the gateway, and click on Actions > Security > Modify IAM Role.

6. Choose the name of the IAM role created earlier.

If your gateway is deployed in an EKS cluster and you are using IAM Roles for Service Accounts, you will need to set the following environment variable: SDM_AWS_DEFAULT_PRIORITY=true.

Role assumption from EC2 instances

If your EC2 instance is not in the same account as your Secrets Manager, or you wish to provide access to Secrets Manager in a more temporary fashion, you can configure the secret store in StrongDM to use IAM role assumption. IAM role assumption lets the node temporarily take on an AWS IAM role to access a resource.

1. First create an IAM policy in the AWS account that contains the Secrets Manager, which will be assumed by EC2 instances. These EC2 instances can be located in the same AWS account or in a different one. We recommend the following policies as part of that role:

"secretsmanager:GetRandomPassword",
"secretsmanager:GetResourcePolicy",
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret",
"secretsmanager:CreateSecret",
"secretsmanager:ListSecretVersionIds",
"secretsmanager:ListSecrets",
"secretsmanager:BatchGetSecretValue",
"secretsmanager:UpdateSecret"

1. Once that is done, open the AWS Management Console for the EC2 instances in question and use IAM role assumption to authenticate it, too. Follow the above instructions to open your EC2 instance (add an IAM role, and add it to the EC2 instance) but for the role, instead of adding the SecretsManagerReadWrite policy, write a custom policy allowing it to assume a role in your Secrets Manager AWS account (filling in your own role here):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::000111222333:role/ExampleAccessSecretsManagerRole"
        }
    ]
}

1. Finally, in StrongDM, when you set up your Secrets Manager, make sure you fill in the Assume Role ARN and Assume Role External ID fields. When a Role ARN for a StrongDM resource, StrongDM uses AWS AssumeRole so that nodes connecting to that resource inherit the role’s permissions for the session (optionally with an External ID to verify with EC2 instances in other accounts). See the AWS documentation for more on external IDs.

You can also, using this role assumption method, set up the same Secrets Manager instance multiple times as separate secret stores in StrongDM, with separate roles to be assumed, each with different permissions in Secrets Manager. Nodes attached to StrongDM would all have the same role assumption policy that lists all of the available roles as Resources, but the secret store that the StrongDM resource is attached to will dictate which is chosen for role assumption and therefore which permissions in Secrets Manager are available.

Option 3: ECS authentication

In the task definition for the ECS cluster, the Task Role must have a policy allowing access to Secrets Manager attached to it, as in the following example:

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

If Resource Permissions is configured for Secrets Manager, the policy statement also needs to allow the Task Role to access that particular Secrets Manager.

Credential reading order

During authentication with Secrets Manager, the system looks for credentials in the following places in this order:

1. Environment variables

2. EC2 role

3. ECS authentication or other remote authentication methods (set via AWS_CONTAINER_CREDENTIALS_FULL_URI or AWS_CONTAINER_CREDENTIALS_RELATIVE_URI)

4. Shared credentials file

As soon as the relay or gateway finds credentials, it stops searching and uses them. Due to this behavior, we recommend that all similar AWS resources with these authentication options use the same method when added to StrongDM.

For example, if you are using environment variables for AWS Management Console and using EC2 role authentication for an EKS cluster, when users attempt to connect to the EKS cluster through the gateway or relay, the environment variables are found and used in an attempt to authenticate with the EKS cluster, which then fails. We recommend using the same type for all such resources to avoid this problem at the gateway or relay level. Alternatively, you can segment your network by creating subnets with their own relays and sets of resources, so that the relays can be configured to work correctly with just those resources.

This behavior was changed in CLI version 39.51.0. If you experience unexpected errors when upgrading to this version or above, you can set the environment variable SDM_AWS_LEGACY_PRIORITY to a truthy value such as 1 or true, to temporarily revert to the old behavior. In a future release, this option will go away.

If you would prefer to alter the priority of credentials to follow the default order specified by Configuring the AWS SDK for Go - AWS SDK for Go (version 1) in the "Specifying Credentials" section, you may set the environment variable SDM_AWS_DEFAULT_PRIORITY to a truthy value such as 1 or true.

Configure the Secret Store with the Admin UI

Once you have AWS Secrets Manager set up, credentials stored, and your Relay server able to access said credentials, it's time to integrate the secret store with StrongDM.

1. In the Admin UI, go to Settings > Secrets Management and to the Secret Stores tab.

2. Click the add secret store button.

3. On the Add Secret Store form, set the following:

   1. Display Name: Enter a name. This name will show up in the Admin UI.

   2. Secret Store Type: Select AWS Secrets Manager.

   3. Region: Fill the AWS region (e.g., us-west-2) for your AWS Secrets Manager.

4. If you are using role assumption, you may also need to fill in these two fields:

   1. Assume Role ARN: Amazon Resource Name (ARN) role; If the Role ARN is filled, it will be assumed after login (for example, arn:aws:iam::000000000000:role/RoleName); required for role assumption

   2. Assume Role External ID: External ID role to assume after login (for example 12345); optional for role assumption, if you wish to use an external id for access from outside the Secret Manager's AWS account; see the AWS documentation for more on external IDs.

If you've configured the Relay server correctly for secret store access and authorization, you will see the green online indicator.

Now, create a resource that uses the secret store, assign it to a Role that is assigned to a User, and verify that you can connect.

1. In the Admin UI, add a new resource such as a Server or Datasource and choose the AWS Secrets Manager Secret Store type.

2. Fill out the information for a resource whose credentials you have stored in your secret store.

3. Select the AWS Secrets Store you created for the Secret Store field, and then fill in the ARN to the secrets that you've stored in your secret store.

   1. AWS accepts plaintext secrets, which you would use to store one credential field per secret, or you can write out JSON secrets in the field, which could include many credential values with different keys. If using JSON, add the key along with the path to the credential, (e.g., arn:aws:secretsmanager:us-west-2:111122223333:?key=username).

   2. It is preferred that certificates be Base64-encoded. If the secret you are storing is a certificate, you should Base64-encode it, and then enter the path as follows when setting up a resource to use it: arn:aws:secretsmanager:us-west-2:111122223333:example-secret?key=certificate&encoding=base64.

4. Submit the form.

5. Go to Roles, create a Role with an access rule that grants access to the resource, and assign the Role to the User.

6. Log in as that User in your local GUI (or have the User do so, if not yours) and verify that the resource exists, test a connection, and execute a query.

Congratulations, you've connected to a resource using secret stores.