AWS Secret Manager

Secret Agent can fetch secrets from AWS Secrets Manager in the following ways:

1. Instance Metadata Service(IMDS)
2. Static Credentials
3. Assume Role provider

Instance Metadata Service (IMDS)

IMDS is the best way to fetch secrets from AWS, because it does not require any AWS credentials to be specified in the configuration file. When Secret Agent runs on an EC2 instance with an IAM role attached to it, 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 it.

Use the following procedure 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 the secret TestingSecret.
3. Create an IAM role for Secret Agent to use. 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 to it.
6. Install Secret Agent on the EC2 instance.
7. Configure Secret Agent to fetch secrets from AWS Secrets Manager.
8. Start Secret Agent.
9. Use the Secret Agent endpoint to fetch secrets.

The following is a sample configuration file for Secret Agent to use AWS 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

The following is a sample EC2 configuration which gives the instance permission to access secrets:

{
  "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 also run on any machine with AWS static credentials configured in the configuration file. You can use Static Credentials mode even when Secret Agent is running on an EC2 instance without any IAM role attached to it. Static Credentials mode is also useful when Secret Agent uses a different IAM role from the one attached to the EC2 instance.

Static Credentials mode looks for 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 environment variable AWS_PROFILE.
4. EC2 instance profile credentials.

Use the following procedure to configure Secret Agent to use AWS static credentials:

1. Create an IAM user. In this example, the user is named SecretAgent.
2. Create a secret in AWS Secrets Manager. In this example, the secret is named TestingSecret.
3. Add one or more key value pairs to the secret TestingSecret.
4. Give the GetSecretValue permission to the IAM user SecretAgent on the secret TestingSecret.
5. Install Secret Agent on the EC2 instance.
6. Configure Secret Agent and specify the IAM user credentials in the config file.
7. Start Secret Agent.
8. Use the Secret Agent endpoint to fetch secrets.

The following is a sample configuration file for Secret Agent in Static Credentials mode:

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

In some cases, the static credentials must be configured in the shared credentials file. The following is a sample Secret Agent configuration file and shared credentials file.

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

[default]
aws_access_key_id = AAAAAAAAAAAAAAAAAAAA
aws_secret_access_key = AAAAAAA/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The shared credentials file can also be used to specify temporary security credentials via AWS STS. They include a dynamically generated access key ID, a secret access key, and a security token. There are many different ways to generate temporary security credentials. Refer to the AWS STS documentation for more details.

Temporary security credentials are valid for a limited time period. When they expire, Secret Agent automatically fetches the latest credentials from the shared credentials file. The latest credentials should be populated before they expire (preferably via automation).

The three values should be specified in the shared credentials file as shown below:

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

The following is a sample configuration which gives permission to an IAM user to access secrets:

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

Assume Role

You can use Assume Role mode on top of the above two modes (IMDS & Static Credentials). Secret Agent starts with the configured credentials (source credentials) and then assumes the specified role by generating temporary credentials using the AWS Security Token Service.

Use the following procedure:

1. Create an AWS user, if you don't have one already. In this example, the AWS user is named SecretOwner.
2. Create a secret in AWS Secrets Manager. In this example, the secret is named TestingSecret and it belongs to user SecretOwner.
3. Add one or more key value pairs to the secret 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.
12. Use the Secret Agent endpoint to fetch secrets.

The following is a sample configuration file for Secret Agent for the Assume Role mode when using 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
    assume-role: arn:aws:iam::999999999999:role/AccessToSecrets
    access-key-id: AAAAAAAAAAAAAAAAAAAA # key id of user SecretAgent (not SecretOwner)
    secret-access-key: AAAAAAA/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # secret key of user SecretAgent (not SecretOwner)

log:
  level: info

The following is a sample configuration to give a trust relationship for an IAM user to a role.

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

In the example above, Secret Agent starts with the credentials of user SecretAgent. It then assumes the role AccessToSecrets and generate temporary credentials. These temporary credentials are used to fetch secrets from AWS Secrets Manager. Notice that we are not using the credentials of user SecretOwner anywhere in the configuration.

This example uses a statically created IAM user, but you can achieve the same result by using temporary security credentials generated via AWS STS. The temporary security credentials should have permission to assume the role AccessToSecrets.