open-vault/website/source/docs/secrets/aws/index.html.md

layout	page_title	sidebar_current	description
docs	Secret Backend: AWS	docs-secrets-aws	The AWS secret backend for Vault generates access keys dynamically based on IAM policies.

AWS Secret Backend

Name: aws

The AWS secret backend for Vault generates AWS access credentials dynamically based on IAM policies. This makes IAM much easier to use: credentials could be generated on the fly, and are automatically revoked when the Vault lease is expired.

This page will show a quick start for this backend. For detailed documentation on every path, use vault help after mounting the backend.

Quick Start

The first step to using the aws backend is to mount it. Unlike the generic backend, the aws backend is not mounted by default.

$ vault mount aws
Successfully mounted 'aws' at 'aws'!

Next, we must configure the root credentials that are used to manage IAM credentials:

$ vault write aws/config/root \
    access_key=AKIAJWVN5Z4FOFT7NLNA \
    secret_key=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 \
    region=us-east-1

The following parameters are required:

• access_key - the AWS access key that has permission to manage IAM credentials.
• secret_key - the AWS secret key that has permission to manage IAM credentials.
• region the AWS region for API calls.

The next step is to configure a role. A role is a logical name that maps to a policy used to generated those credentials. For example, lets create a "deploy" role:

$ vault write aws/roles/deploy \
    name=deploy \
    policy=@policy.json

This path will create a named role along with the IAM policy used to restrict permissions for it. This is used to dynamically create a new pair of IAM credentials when needed.

The @ tells Vault to load the policy from the file named policy.json. Here is an example IAM policy to get started:

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": "iam:*",
    "Resource": "*"
  }
}

For more information on IAM policies, please see the AWS IAM policy documentation.

To generate a new set of IAM credentials, we simply read from that role:

$ vault read aws/creds/deploy
Key             Value
lease_id        aws/creds/deploy/7cb8df71-782f-3de1-79dd-251778e49f58
lease_duration  3600
access_key      AKIAIOMYUTSLGJOGLHTQ
secret_key      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

If you run the command again, you will get a new set of credentials:

$ vault read aws/creds/deploy
Key             Value
lease_id        aws/creds/deploy/82d89562-ff19-382e-6be9-cb45c8f6a42d
lease_duration  3600
access_key      AKIAJZ5YRPHFH3QHRRRQ
secret_key      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

If you get stuck at any time, simply run vault help aws or with a subpath for interactive help output.

API

/aws/config/root

POST

Description

Configures the root IAM credentials used. This is a root protected endpoint.

Method

POST

URL

`/aws/config/root`

Parameters

• access_key required The AWS Access Key
• secret_key required The AWS Secret Key
• region required The AWS region for API calls

Returns

A `204` response code.

/aws/config/lease

POST

Description

Configures the lease settings for generated credentials. This is a root protected endpoint.

Method

POST

URL

`/aws/config/lease`

Parameters

• lease required The lease value provided as a string duration with time suffix. Hour is the largest suffix.
• lease_max required The maximum lease value provided as a string duration with time suffix. Hour is the largest suffix.

Returns

A `204` response code.

/aws/roles/

POST

Description

Creates or updates a named role.

Method

POST

URL

`/aws/roles/`

Parameters

• policy required The IAM policy in JSON format.

Returns

A `204` response code.

GET

Description

Queries a named role.

Method

GET

URL

`/aws/roles/`

Parameters

None

Returns

```javascript
{
    "data": {
        "policy": "..."
    }
}
```

DELETE

Description

Deletes a named role.

Method

DELETE

URL

`/aws/roles/`

Parameters

None

Returns

A `204` response code.

/aws/creds/

GET

Description

Generates a dynamic IAM credential based on the named role.

Method

GET

URL

`/aws/creds/`

Parameters

None

Returns

```javascript
{
    "data": {
        "access_key": "...",
        "secret_key": "..."
    }
}
```