# AWS Secrets Manager

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

1.  [Instance Metadata Service (IMDS)](https://docs.aws.amazon.com/sdkref/latest/guide/feature-imds-credentials.html)
2.  [Static credentials](https://docs.aws.amazon.com/sdkref/latest/guide/feature-static-credentials.html)
3.  [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)

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

```yaml
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:

```json
{

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

```yaml
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:

```yaml
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`):

```ini
[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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html). 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:

```ini
[default]

aws_access_key_id = AAAAAAAAAAAAAAAAAAAA

aws_secret_access_key = AAAAAAA/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

aws_session_token = TTTTTTTTTTTTTTTTTTTT
```

See the [AWS STS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) for details on generating temporary credentials.

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

```json
{

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

```yaml
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:

```json
{

  "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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) as the source credentials. The temporary credentials must have permission to assume the role `AccessToSecrets`.