luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity
open-vault/website/content/docs/secrets/aws.mdx
Jeff Escalante ec620a7765
Implement MDX Remote (#10581) 
* implement mdx remote

* fix an unfenced code block

* fix partials path

Co-authored-by: Jim Kalafut <jkalafut@hashicorp.com>
2020-12-17 16:53:33 -05:00

469 lines
17 KiB
Plaintext
Raw Blame History

---
layout: docs
page_title: AWS - Secrets Engines
sidebar_title: AWS
description: |-
The AWS secrets engine for Vault generates access keys dynamically based on
IAM policies.
---
# AWS Secrets Engine
The AWS secrets engine generates AWS access credentials dynamically based on IAM
policies. This generally makes working with AWS IAM easier, since it does not
involve clicking in the web UI. Additionally, the process is codified and mapped
to internal auth methods (such as LDAP). The AWS IAM credentials are time-based
and are automatically revoked when the Vault lease expires.
Vault supports three different types of credentials to retrieve from AWS:
1. `iam_user`: Vault will create an IAM user for each lease, attach the managed
and inline IAM policies as specified in the role to the user, and if a
[permissions
boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)
is specified on the role, the permissions boundary will also be attached.
Vault will then generate an access key and secret key for the IAM user and
return them to the caller. IAM users have no session tokens and so no
session token will be returned. Vault will delete the IAM user upon reaching the TTL expiration.
2. `assumed_role`: Vault will call
[sts:AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)
and return the access key, secret key, and session token to the caller.
3. `federation_token`: Vault will call
[sts:GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html)
passing in the supplied AWS policy document and return the access key, secret
key, and session token to the caller.
## Setup
Most secrets engines must be configured in advance before they can perform their
functions. These steps are usually completed by an operator or configuration
management tool.
1. Enable the AWS secrets engine:
```text
$ vault secrets enable aws
Success! Enabled the aws secrets engine at: aws/
```
By default, the secrets engine will mount at the name of the engine. To
enable the secrets engine at a different path, use the `-path` argument.
1. Configure the credentials that Vault uses to communicate with AWS to generate
the IAM credentials:
```text
$ vault write aws/config/root \
access_key=AKIAJWVN5Z4FOFT7NLNA \
secret_key=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 \
region=us-east-1
```
Internally, Vault will connect to AWS using these credentials. As such,
these credentials must be a superset of any policies which might be granted
on IAM credentials. Since Vault uses the official AWS SDK, it will use the
specified credentials. You can also specify the credentials via the standard
AWS environment credentials, shared file credentials, or IAM role/ECS task
credentials. (Note that you can't authorize vault with IAM role credentials if you plan
on using STS Federation Tokens, since the temporary security credentials
associated with the role are not authorized to use GetFederationToken.)
~> **Notice:** Even though the path above is `aws/config/root`, do not use
your AWS root account credentials. Instead generate a dedicated user or
role.
1. Configure a Vault role that maps to a set of permissions in AWS as well as an
AWS credential type. When users generate credentials, they are generated
against this role. An example:
```text
$ vault write aws/roles/my-role \
credential_type=iam_user \
policy_document=-<<EOF
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:*",
"Resource": "*"
}
]
}
EOF
```
This creates a role named "my-role". When users generate credentials against
this role, Vault will create an IAM user and attach the specified policy
document to the IAM user. Vault will then create an access key and secret
key for the IAM user and return these credentials. You supply a
user inline policy and/or provide references to an existing AWS policy's full
ARN and/or a list of IAM groups:
```text
$ vault write aws/roles/my-other-role \
policy_arns=arn:aws:iam::aws:policy/AmazonEC2ReadOnlyAccess,arn:aws:iam::aws:policy/IAMReadOnlyAccess \
iam_groups=group1,group2 \
credential_type=iam_user \
policy_document=-<<EOF
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "ec2:*",
"Resource": "*"
}
]
}
EOF
```
For more information on IAM policies, please see the
[AWS IAM policy documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/PoliciesOverview.html).
## Usage
After the secrets engine is configured and a user/machine has a Vault token with
the proper permission, it can generate credentials.
1. Generate a new credential by reading from the `/creds` endpoint with the name
of the role:
```text
$ vault read aws/creds/my-role
Key Value
--- -----
lease_id aws/creds/my-role/f3e92392-7d9c-09c8-c921-575d62fe80d8
lease_duration 768h
lease_renewable true
access_key AKIAIOWQXTLW36DV7IEA
secret_key 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
security_token <nil>
```
Each invocation of the command will generate a new credential.
Unfortunately, IAM credentials are eventually consistent with respect to
other Amazon services. If you are planning on using these credential in a
pipeline, you may need to add a delay of 5-10 seconds (or more) after
fetching credentials before they can be used successfully.
If you want to be able to use credentials without the wait, consider using
the STS method of fetching keys. IAM credentials supported by an STS token
are available for use as soon as they are generated.
## Example IAM Policy for Vault
The `aws/config/root` credentials need permission to manage dynamic IAM users.
Here is an example AWS IAM policy that grants the most commonly required
permissions Vault needs:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:AttachUserPolicy",
"iam:CreateAccessKey",
"iam:CreateUser",
"iam:DeleteAccessKey",
"iam:DeleteUser",
"iam:DeleteUserPolicy",
"iam:DetachUserPolicy",
"iam:ListAccessKeys",
"iam:ListAttachedUserPolicies",
"iam:ListGroupsForUser",
"iam:ListUserPolicies",
"iam:PutUserPolicy",
"iam:AddUserToGroup",
"iam:RemoveUserFromGroup"
],
"Resource": ["arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/vault-*"]
}
]
}
```
Vault also supports AWS Permissions Boundaries when creating IAM users. If you
wish to enforce that Vault always attaches a permissions boundary to an IAM
user, you can use a policy like:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:CreateAccessKey",
"iam:DeleteAccessKey",
"iam:DeleteUser",
"iam:ListAccessKeys",
"iam:ListAttachedUserPolicies",
"iam:ListGroupsForUser",
"iam:ListUserPolicies",
"iam:AddUserToGroup",
"iam:RemoveUserFromGroup"
],
"Resource": ["arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/vault-*"]
},
{
"Effect": "Allow",
"Action": [
"iam:AttachUserPolicy",
"iam:CreateUser",
"iam:DeleteUserPolicy",
"iam:DetachUserPolicy",
"iam:PutUserPolicy"
],
"Resource": ["arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/vault-*"],
"Condition": {
"StringEquals": {
"iam:PermissionsBoundary": [
"arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:policy/PolicyName"
]
}
}
}
]
}
```
where the "iam:PermissionsBoundary" condition contains the list of permissions
boundary policies that you wish to ensure that Vault uses. This policy will
ensure that Vault uses one of the permissions boundaries specified (not all of
them).
## STS credentials
The above demonstrated usage with `iam_user` credential types. As mentioned,
Vault also supports `assumed_role` and `federation_token` credential types.
### STS Federation Tokens
~> **Notice:** Due to limitations in AWS, in order to use the `federation_token`
credential type, Vault **must** be configured with IAM user credentials. AWS
does not allow temporary credentials (such as those from an IAM instance
profile) to be used.
An STS federation token inherits a set of permissions that are the combination
(intersection) of four sets of permissions:
1. The permissions granted to the `aws/config/root` credentials
2. The user inline policy configured in the Vault role
3. The managed policy ARNs configured in the Vault role
4. An implicit deny policy on IAM or STS operations.
Roles with a `credential_type` of `federation_token` can specify one or more of
the `policy_document`, `policy_arns`, and `iam_groups` parameters in the Vault
role.
The `aws/config/root` credentials require IAM permissions for
`sts:GetFederationToken` and the permissions to delegate to the STS
federation token. For example, this policy on the `aws/config/root` credentials
would allow creation of an STS federated token with delegated `ec2:*`
permissions (or any subset of `ec2:*` permissions):
```javascript
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"ec2:*",
"sts:GetFederationToken"
],
"Resource": "*"
}
}
```
An `ec2_admin` role would then assign an inline policy with the same `ec2:*`
permissions.
```shell-session
$ vault write aws/roles/ec2_admin \
credential_type=federation_token \
policy_document=@policy.json
```
The policy.json file would contain an inline policy with similar permissions,
less the `sts:GetFederationToken` permission. (We could grant
`sts:GetFederationToken` permissions, but STS attaches attach an implicit deny
that overrides the allow.)
```javascript
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "ec2:*",
"Resource": "*"
}
}
```
To generate a new set of STS federation token credentials, we simply write to
the role using the aws/sts endpoint:
```shell-session
$ vault write aws/sts/ec2_admin ttl=60m
Key Value
lease_id aws/sts/ec2_admin/31d771a6-fb39-f46b-fdc5-945109106422
lease_duration 60m0s
lease_renewable false
access_key ASIAJYYYY2AA5K4WIXXX
secret_key HSs0DYYYYYY9W81DXtI0K7X84H+OVZXK5BXXXX
security_token AQoDYXdzEEwasAKwQyZUtZaCjVNDiXXXXXXXXgUgBBVUUbSyujLjsw6jYzboOQ89vUVIehUw/9MreAifXFmfdbjTr3g6zc0me9M+dB95DyhetFItX5QThw0lEsVQWSiIeIotGmg7mjT1//e7CJc4LpxbW707loFX1TYD1ilNnblEsIBKGlRNXZ+QJdguY4VkzXxv2urxIH0Sl14xtqsRPboV7eYruSEZlAuP3FLmqFbmA0AFPCT37cLf/vUHinSbvw49C4c9WQLH7CeFPhDub7/rub/QU/lCjjJ43IqIRo9jYgcEvvdRkQSt70zO8moGCc7pFvmL7XGhISegQpEzudErTE/PdhjlGpAKGR3d5qKrHpPYK/k480wk1Ai/t1dTa/8/3jUYTUeIkaJpNBnupQt7qoaXXXXXXXXXX
```
### STS AssumeRole
The `assumed_role` credential type is typically used for cross-account
authentication or single sign-on (SSO) scenarios. In order to use an
`assumed_role` credential type, you must configure outside of Vault:
1. An IAM role
2. IAM inline policies and/or managed policies attached to the IAM role
3. IAM trust policy attached to the IAM role to grant privileges for Vault to
assume the role
`assumed_role` credentials offer a few benefits over `federation_token`:
1. Assumed roles can invoke IAM and STS operations, if granted by the role's
IAM policies.
2. Assumed roles support cross-account authentication
3. Temporary credentials (such as those granted by running Vault on an EC2
instance in an IAM instance profile) can retrieve `assumed_role` credentials
(but cannot retrieve `federation_token` credentials).
The `aws/config/root` credentials must have an IAM policy that allows `sts:AssumeRole`
against the target role:
```javascript
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/RoleNameToAssume"
}
}
```
You must attach a trust policy to the target IAM role to assume, allowing
the aws/root/config credentials to assume the role.
```javascript
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:user/VAULT-AWS-ROOT-CONFIG-USER-NAME"
},
"Action": "sts:AssumeRole"
}
]
}
```
When specifying a Vault role with a `credential_type` of `assumed_role`, you can
specify more than one IAM role ARN. If you do so, Vault clients can select which
role ARN they would like to assume when retrieving credentials from that role.
Further, you can specify both a `policy_document` and `policy_arns` parameters;
if specified, each acts as a filter on the IAM permissions granted to the
assumed role. If `iam_groups` is specified, the inline and attached policies for
each IAM group will be added to the `policy_document` and `policy_arns`
parameters, respectively, when calling [sts:AssumeRole]. For an action to be
allowed, it must be permitted by both the IAM policy on the AWS role that is
assumed, the `policy_document` specified on the Vault role (if specified), and
the managed policies specified by the `policy_arns` parameter. (The
`policy_document` parameter is passed in as the `Policy` parameter to the
[sts:AssumeRole] API call, while the `policy_arns` parameter is passed in as the
`PolicyArns` parameter to the same call.)
Note: When multiple `role_arns` are specified, clients requesting credentials
can specify any of the role ARNs that are defined on the Vault role in order to
retrieve credentials. However, when `policy_document`, `policy_arns`, or
`iam_groups` are specified, that will apply to ALL role credentials retrieved
from AWS.
Let's create a "deploy" policy using the arn of our role to assume:
```shell-session
$ vault write aws/roles/deploy \
role_arns=arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/RoleNameToAssume \
credential_type=assumed_role
```
To generate a new set of STS assumed role credentials, we again write to
the role using the aws/sts endpoint:
```shell-session
$ vault write aws/sts/deploy ttl=60m
Key Value
lease_id aws/sts/deploy/31d771a6-fb39-f46b-fdc5-945109106422
lease_duration 60m0s
lease_renewable false
access_key ASIAJYYYY2AA5K4WIXXX
secret_key HSs0DYYYYYY9W81DXtI0K7X84H+OVZXK5BXXXX
security_token AQoDYXdzEEwasAKwQyZUtZaCjVNDiXXXXXXXXgUgBBVUUbSyujLjsw6jYzboOQ89vUVIehUw/9MreAifXFmfdbjTr3g6zc0me9M+dB95DyhetFItX5QThw0lEsVQWSiIeIotGmg7mjT1//e7CJc4LpxbW707loFX1TYD1ilNnblEsIBKGlRNXZ+QJdguY4VkzXxv2urxIH0Sl14xtqsRPboV7eYruSEZlAuP3FLmqFbmA0AFPCT37cLf/vUHinSbvw49C4c9WQLH7CeFPhDub7/rub/QU/lCjjJ43IqIRo9jYgcEvvdRkQSt70zO8moGCc7pFvmL7XGhISegQpEzudErTE/PdhjlGpAKGR3d5qKrHpPYK/k480wk1Ai/t1dTa/8/3jUYTUeIkaJpNBnupQt7qoaXXXXXXXXXX
```
[sts:assumerole]: https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html
## Troubleshooting
### Dynamic IAM user errors
If you get an error message similar to either of the following, the root credentials that you wrote to `aws/config/root` have insufficient privilege:
```shell-session
$ vault read aws/creds/deploy
* Error creating IAM user: User: arn:aws:iam::000000000000:user/hashicorp is not authorized to perform: iam:CreateUser on resource: arn:aws:iam::000000000000:user/vault-root-1432735386-4059
$ vault revoke aws/creds/deploy/774cfb27-c22d-6e78-0077-254879d1af3c
Revoke error: Error making API request.
URL: PUT http://127.0.0.1:8200/v1/sys/revoke/aws/creds/deploy/774cfb27-c22d-6e78-0077-254879d1af3c
Code: 400. Errors:
* invalid request
```
If you get stuck at any time, simply run `vault path-help aws` or with a subpath for
interactive help output.
### STS federated token errors
Vault generates STS tokens using the IAM credentials passed to `aws/config`.
Those credentials must have two properties:
- They must have permissions to call `sts:GetFederationToken`.
- The capabilities of those credentials have to be at least as permissive as those requested
by policies attached to the STS creds.
If either of those conditions are not met, a "403 not-authorized" error will be returned.
See http://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html for more details.
Vault 0.5.1 or later is recommended when using STS tokens to avoid validation
errors for exceeding the AWS limit of 32 characters on STS token names.
### AWS Instance Metadata Timeouts
@include 'aws-imds-timeout.mdx'
## API
The AWS secrets engine has a full HTTP API. Please see the
[AWS secrets engine API](/api/secret/aws) for more
details.
Reference in a new issue View git blame Copy permalink