Recommend IAM auth over EC2 (#5772)
* Recommend IAM auth over EC2 * Update website/source/docs/auth/aws.html.md Co-Authored-By: vishalnayak <vishalnayak@users.noreply.github.com> * Update website/source/docs/auth/aws.html.md Co-Authored-By: vishalnayak <vishalnayak@users.noreply.github.com> * Update website/source/docs/auth/aws.html.md Co-Authored-By: vishalnayak <vishalnayak@users.noreply.github.com>
This commit is contained in:
Vishal Nayak
GitHub
parent
5b5c3d2af1
commit
c144bc4b34
|
|
@ -9,35 +9,89 @@ description: |-
|
|||
|
||||
# AWS Auth Method
|
||||
|
||||
The `aws` auth method provides an automated mechanism to retrieve
|
||||
a Vault token for AWS EC2 instances and IAM principals. Unlike most Vault
|
||||
auth methods, this method does not require manual first-deploying, or
|
||||
provisioning security-sensitive credentials (tokens, username/password, client
|
||||
certificates, etc), by operators under many circumstances. It treats
|
||||
AWS as a Trusted Third Party and uses either
|
||||
the cryptographically signed dynamic metadata information that uniquely
|
||||
represents each EC2 instance or a special AWS request signed with AWS IAM
|
||||
credentials. The metadata information is automatically supplied by AWS to all
|
||||
EC2 instances, and IAM credentials are automatically supplied to AWS instances
|
||||
in IAM instance profiles, Lambda functions, and others, and it is this
|
||||
information already provided by AWS which Vault can use to authenticate
|
||||
clients.
|
||||
The `aws` auth method provides an automated mechanism to retrieve a Vault token
|
||||
for IAM principals and AWS EC2 instances. Unlike most Vault auth methods, this
|
||||
method does not require manual first-deploying, or provisioning
|
||||
security-sensitive credentials (tokens, username/password, client certificates,
|
||||
etc), by operators under many circumstances.
|
||||
|
||||
## Authentication Workflow
|
||||
|
||||
There are two authentication types present in the aws auth method: `ec2` and `iam`.
|
||||
There are two authentication types present in the aws auth method: `iam` and
|
||||
`ec2`.
|
||||
|
||||
With the `iam` method, a special AWS request signed with AWS IAM credentials is
|
||||
used for authentication. The IAM credentials are automatically supplied to AWS
|
||||
instances in IAM instance profiles, Lambda functions, and others, and it is
|
||||
this information already provided by AWS which Vault can use to authenticate
|
||||
clients.
|
||||
|
||||
With the `ec2` method, AWS is treated as a Trusted Third Party and
|
||||
cryptographically signed dynamic metadata information that uniquely represents
|
||||
each EC2 instance is used for authentication. This metadata information is
|
||||
automatically supplied by AWS to all EC2 instances.
|
||||
|
||||
Based on how you attempt to authenticate, Vault will determine if you are
|
||||
attempting to use the `ec2` or `iam` type. Each has a different authentication
|
||||
workflow, and each can solve different use cases. See the section on comparing
|
||||
the two auth methods below to help determine which method is more appropriate
|
||||
for your use cases.
|
||||
attempting to use the `iam` or `ec2` type. Each has a different authentication
|
||||
workflow, and each can solve different use cases.
|
||||
|
||||
Note: The `ec2` method was implemented before the primitives to implement the
|
||||
`iam` method were supported by AWS. The `iam` method is the recommended approach
|
||||
as it is more flexible and aligns with best practices to perform access
|
||||
control and authentication. See the section on comparing the two auth methods
|
||||
below for more information.
|
||||
|
||||
### IAM auth method
|
||||
|
||||
The AWS STS API includes a method,
|
||||
[`sts:GetCallerIdentity`](http://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html),
|
||||
which allows you to validate the identity of a client. The client signs a
|
||||
`GetCallerIdentity` query using the [AWS Signature v4
|
||||
algorithm](http://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) and
|
||||
submits 4 pieces of information to the Vault server to recreate a valid signed
|
||||
request: the request URL, the request body, the request headers, and the
|
||||
request method, as the AWS signature is computed over those fields. The Vault
|
||||
server then reconstructs the query and forwards it on to the AWS STS service
|
||||
and validates the result back. Clients don't need network-level access to talk
|
||||
to the AWS STS API endpoint; they merely need access to the credentials to sign
|
||||
the request. However, it means that the Vault server does need network-level
|
||||
access to send requests to the STS endpoint.
|
||||
|
||||
Importantly, the credentials used to sign the GetCallerIdentity request can
|
||||
come from the EC2 instance metadata service for an EC2 instance, or from the
|
||||
AWS environment variables in an AWS Lambda function execution, which obviates
|
||||
the need for an operator to manually provision some sort of identity material
|
||||
first. However, the credentials can, in principle, come from anywhere, not
|
||||
just from the locations AWS has provided for you.
|
||||
|
||||
Each signed AWS request includes the current timestamp to mitigate the risk of
|
||||
replay attacks. In addition, Vault allows you to require an additional header,
|
||||
`X-Vault-AWS-IAM-Server-ID`, to be present to mitigate against different types
|
||||
of replay attacks (such as a signed `GetCallerIdentity` request stolen from a
|
||||
dev Vault instance and used to authenticate to a prod Vault instance). Vault
|
||||
further requires that this header be one of the headers included in the AWS
|
||||
signature and relies upon AWS to authenticate that signature.
|
||||
|
||||
While AWS API endpoints support both signed GET and POST requests, for
|
||||
simplicity, the aws auth method supports only POST requests. It also does not
|
||||
support `presigned` requests, i.e., requests with `X-Amz-Credential`,
|
||||
`X-Amz-Signature`, and `X-Amz-SignedHeaders` GET query parameters containing
|
||||
the authenticating information.
|
||||
|
||||
It's also important to note that Amazon does NOT appear to include any sort of
|
||||
authorization around calls to `GetCallerIdentity`. For example, if you have an
|
||||
IAM policy on your credential that requires all access to be MFA authenticated,
|
||||
non-MFA authenticated credentials (i.e., raw credentials, not those retrieved
|
||||
by calling `GetSessionToken` and supplying an MFA code) will still be able to
|
||||
authenticate to Vault using this method. It does not appear possible to enforce
|
||||
an IAM principal to be MFA authenticated while authenticating to Vault.
|
||||
|
||||
### EC2 auth method
|
||||
|
||||
Amazon EC2 instances have access to metadata which describes the instance. The
|
||||
Vault EC2 auth method leverages the components of this metadata to
|
||||
authenticate and distribute an initial Vault token to an EC2 instance. The data
|
||||
flow (which is also represented in the graphic below) is as follows:
|
||||
Vault EC2 auth method leverages the components of this metadata to authenticate
|
||||
and distribute an initial Vault token to an EC2 instance. The data flow (which
|
||||
is also represented in the graphic below) is as follows:
|
||||
|
||||
[](/img/vault-aws-ec2-auth-flow.png)
|
||||
|
||||
|
|
@ -64,51 +118,6 @@ instance metadata.
|
|||
There are various modifications to this workflow that provide more or less
|
||||
security, as detailed later in this documentation.
|
||||
|
||||
### IAM auth method
|
||||
|
||||
The AWS STS API includes a method,
|
||||
[`sts:GetCallerIdentity`](http://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html),
|
||||
which allows you to validate the identity of a client. The client signs
|
||||
a `GetCallerIdentity` query using the [AWS Signature v4
|
||||
algorithm](http://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) and
|
||||
submits 4 pieces of information to the Vault server to recreate a valid signed
|
||||
request: the request URL, the request body, the request headers, and the request
|
||||
method, as the AWS signature is computed over those fields. The Vault server
|
||||
then reconstructs the query and forwards it on to the AWS STS service and
|
||||
validates the result back. Clients don't need network-level access to talk to
|
||||
the AWS STS API endpoint; they merely need access to the credentials to sign the
|
||||
request. However, it means that the Vault server does need network-level access
|
||||
to send requests to the STS endpoint.
|
||||
|
||||
Importantly, the credentials used to sign the GetCallerIdentity request can come
|
||||
from the EC2 instance metadata service for an EC2 instance, or from the AWS
|
||||
environment variables in an AWS Lambda function execution, which obviates the
|
||||
need for an operator to manually provision some sort of identity material first.
|
||||
However, the credentials can, in principle, come from anywhere, not just from
|
||||
the locations AWS has provided for you.
|
||||
|
||||
Each signed AWS request includes the current timestamp to mitigate the risk of
|
||||
replay attacks. In addition, Vault allows you to require an additional header,
|
||||
`X-Vault-AWS-IAM-Server-ID`, to be present to mitigate against different types of replay
|
||||
attacks (such as a signed `GetCallerIdentity` request stolen from a dev Vault
|
||||
instance and used to authenticate to a prod Vault instance). Vault further
|
||||
requires that this header be one of the headers included in the AWS signature
|
||||
and relies upon AWS to authenticate that signature.
|
||||
|
||||
While AWS API endpoints support both signed GET and POST requests, for
|
||||
simplicity, the aws auth method supports only POST requests. It also does not
|
||||
support `presigned` requests, i.e., requests with `X-Amz-Credential`,
|
||||
`X-Amz-Signature`, and `X-Amz-SignedHeaders` GET query parameters containing the
|
||||
authenticating information.
|
||||
|
||||
It's also important to note that Amazon does NOT appear to include any sort
|
||||
of authorization around calls to `GetCallerIdentity`. For example, if you have
|
||||
an IAM policy on your credential that requires all access to be MFA authenticated,
|
||||
non-MFA authenticated credentials (i.e., raw credentials, not those retrieved
|
||||
by calling `GetSessionToken` and supplying an MFA code) will still be able to
|
||||
authenticate to Vault using this method. It does not appear possible to enforce
|
||||
an IAM principal to be MFA authenticated while authenticating to Vault.
|
||||
|
||||
## Authorization Workflow
|
||||
|
||||
The basic mechanism of operation is per-role. Roles are registered in the
|
||||
|
|
@ -224,12 +233,12 @@ role. Some examples of how this works in practice:
|
|||
must login using the iam method; the RoleSessionName must be a valid instance
|
||||
ID viewable by Vault, and the instance must have come from the bound AMI ID.
|
||||
|
||||
## Comparison of the EC2 and IAM Methods
|
||||
## Comparison of the IAM and EC2 Methods
|
||||
|
||||
The iam and ec2 auth methods serve similar and somewhat overlapping
|
||||
functionality, in that both authenticate some type of AWS entity to Vault. To
|
||||
help you determine which method is more appropriate for your use case, here is a
|
||||
comparison of the two auth methods.
|
||||
functionality, in that both authenticate some type of AWS entity to Vault.
|
||||
Here are some comparisons that illustrate why `iam` method is preferred over
|
||||
`ec2`.
|
||||
|
||||
* What type of entity is authenticated:
|
||||
* The ec2 auth method authenticates only AWS EC2 instances and is specialized
|
||||
|
|
|
|||
Loading…
Reference in New Issue