Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve clarity of IAM flow explanation #8275

Merged
merged 1 commit into from
Feb 3, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 6 additions & 18 deletions website/pages/docs/auth/aws.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,27 +41,15 @@ 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
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 sends it to the Vault server. 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.

The `GetCallerIdentity` query consists of four pieces of information: 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 reconstructs the query using this information and forwards it on to the AWS STS service. Depending on the response from the STS service, the server authenticates the client.

Notably, clients don't need network-level access themselves 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
Expand Down Expand Up @@ -99,7 +87,7 @@ is also represented in the graphic below) is as follows:
(by region) which can be used to verify the signature.

1. The AWS EC2 instance makes a request to Vault with the PKCS#7 signature.
The PKCS#7 signature contains the Instance Identity Document within itself.
The PKCS#7 signature contains the Instance Identity Document.

1. Vault verifies the signature on the PKCS#7 document, ensuring the information
is certified accurate by AWS. This process validates both the validity and
Expand Down