From 0a9a0ba9aecabe727cc342b7aaa47086bad303db Mon Sep 17 00:00:00 2001 From: Vishal Nayak Date: Tue, 13 Nov 2018 18:49:25 -0500 Subject: [PATCH] Recommend IAM auth over EC2 (#5772) * Recommend IAM auth over EC2 * Update website/source/docs/auth/aws.html.md Co-Authored-By: vishalnayak * Update website/source/docs/auth/aws.html.md Co-Authored-By: vishalnayak * Update website/source/docs/auth/aws.html.md Co-Authored-By: vishalnayak --- website/source/docs/auth/aws.html.md | 149 ++++++++++++++------------- 1 file changed, 79 insertions(+), 70 deletions(-) diff --git a/website/source/docs/auth/aws.html.md b/website/source/docs/auth/aws.html.md index ced5ccf764..8d3e0f07ea 100644 --- a/website/source/docs/auth/aws.html.md +++ b/website/source/docs/auth/aws.html.md @@ -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: [![Vault AWS EC2 Authentication Flow](/img/vault-aws-ec2-auth-flow.png)](/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