AWS Secrets Manager

Secret Agent can authenticate with AWS Secrets Manager using the following methods:

1. Instance Metadata Service (IMDS)
2. Static credentials
3. AssumeRole

Instance Metadata Service (IMDS)

IMDS is the recommended way to authenticate with AWS because it does not require any AWS credentials in the Secret Agent configuration file. When Secret Agent runs on an EC2 instance with an IAM role attached, it automatically uses the Identity and Access Management (IAM) role to fetch secrets from AWS Secrets Manager. The IAM role must have a SecretsManagerReadWrite policy attached.

To configure Secret Agent to use AWS IMDS:

1. Create a secret in AWS Secrets Manager. In this example, the secret is named TestingSecret.
2. Add one or more key-value pairs to TestingSecret.
3. Create an IAM role for Secret Agent. In this example, the role is named AccessToSecrets.
4. Attach a SecretsManagerReadWrite policy to the IAM role AccessToSecrets.
5. Create an EC2 instance with the IAM role AccessToSecrets attached.
6. Install Secret Agent on the EC2 instance.
7. Configure Secret Agent to fetch secrets from AWS Secrets Manager.
8. Start Secret Agent.

Sample configuration file for IMDS:

service:
  tcp:
    endpoint: 0.0.0.0:3005

secret-manager:
  aws:
    region: us-west-1
    resources:
      TestingSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:TestingSecret-tN6s2j

log:
  level: info

Sample EC2 IAM policy that grants access to the secret:

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-west-1:999999999999:secret:TestingSecret-tN6s2j"
    }
  ]
}

Static credentials

Secret Agent can run on any machine with AWS static credentials. You can use static credentials even when Secret Agent runs on an EC2 instance without an IAM role, or when you need to use a different IAM identity from the one attached to the instance.

Secret Agent looks for static credentials in the following order:

1. Secret Agent configuration file.
2. The environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
3. The shared credentials file ~/.aws/credentials and the environment variable AWS_PROFILE.
4. EC2 instance profile credentials.

To configure Secret Agent to use static credentials:

1. Create an IAM user, for example SecretAgent.
2. Create a secret in AWS Secrets Manager, for example TestingSecret.
3. Add one or more key-value pairs to TestingSecret.
4. Grant the GetSecretValue permission to the IAM user SecretAgent on TestingSecret.
5. Install Secret Agent on the machine.
6. Configure Secret Agent and specify the IAM user credentials in the configuration file.
7. Start Secret Agent.

Sample configuration file with credentials specified directly:

service:
  tcp:
    endpoint: 0.0.0.0:3005

secret-manager:
  aws:
    region: us-west-1
    resources:
      TestingSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:TestingSecret-tN6s2j
    access-key-id: AAAAAAAAAAAAAAAAAAAA
    secret-access-key: AAAAAAA/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

log:
  level: info

You can also store credentials in the shared credentials file instead of the Secret Agent configuration file.

Sample Secret Agent configuration file without inline credentials:

service:
  tcp:
    endpoint: 0.0.0.0:3005

secret-manager:
  aws:
    region: us-west-1
    resources:
      TestingSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:TestingSecret-tN6s2j

log:
  level: info

Sample shared credentials file (~/.aws/credentials):

[default]
aws_access_key_id = AAAAAAAAAAAAAAAAAAAA
aws_secret_access_key = AAAAAAA/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Temporary security credentials

The shared credentials file can also hold temporary security credentials from AWS STS. Temporary credentials include a dynamically generated access key ID, a secret access key, and a security token.

Temporary credentials are valid for a limited time. When they expire, Secret Agent automatically fetches the latest credentials from the shared credentials file. You must populate new credentials before the previous ones expire, preferably using automation.

Specify all three values in the shared credentials file:

[default]
aws_access_key_id = AAAAAAAAAAAAAAAAAAAA
aws_secret_access_key = AAAAAAA/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
aws_session_token = TTTTTTTTTTTTTTTTTTTT

See the AWS STS documentation for details on generating temporary credentials.

Sample IAM policy that grants a user access to a secret:

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::999999999999:user/SecretAgent"
      },
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:us-west-1:999999999999:secret:TestingSecret-tN6s2j"
    }
  ]
}

AssumeRole

You can optionally configure Secret Agent to assume an IAM role (AWS STS AssumeRole) on top of either credential source (IMDS or static access keys). Secret Agent starts with the configured source credentials and then assumes the specified role by generating temporary credentials through the AWS Security Token Service (STS).

To configure Secret Agent to assume an IAM role:

1. Create an AWS user, if you don’t have one already. In this example, the user is named SecretOwner.
2. Create a secret in AWS Secrets Manager. In this example, the secret is named TestingSecret and belongs to user SecretOwner.
3. Add one or more key-value pairs to TestingSecret.
4. Create an IAM role. In this example, the role is named AccessToSecrets.
5. Attach a SecretsManagerReadWrite policy to the role AccessToSecrets.
6. Create an IAM user. In this example, the user is named SecretAgent.
7. Create an access key for user SecretAgent.
8. Add the IAM user SecretAgent to a trust relationship of the IAM role AccessToSecrets.
9. Install Secret Agent.
10. Configure Secret Agent and specify the IAM user credentials in the configuration file.
11. Start Secret Agent.

Sample configuration file using AssumeRole with static credentials:

service:
  tcp:
    endpoint: 0.0.0.0:3005

secret-manager:
  aws:
    region: us-west-1
    resources:
      TestingSecret: arn:aws:secretsmanager:us-west-1:999999999999:secret:TestingSecret-tN6s2j
    assume-role: arn:aws:iam::999999999999:role/AccessToSecrets
    access-key-id: AAAAAAAAAAAAAAAAAAAA
    secret-access-key: AAAAAAA/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

log:
  level: info

Sample trust relationship policy that allows an IAM user to assume the role:

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::999999999999:user/SecretAgent"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

In this example, Secret Agent starts with the credentials of user SecretAgent, assumes the role AccessToSecrets, and generates temporary credentials. These temporary credentials are used to fetch secrets from AWS Secrets Manager. The credentials of user SecretOwner are not used in the configuration.

You can also use temporary security credentials generated through AWS STS as the source credentials. The temporary credentials must have permission to assume the role AccessToSecrets.