From e18d4e663a11b24af69d7b80903e464144f4d8eb Mon Sep 17 00:00:00 2001 From: Michael Tibben Date: Mon, 7 May 2018 14:19:16 +1000 Subject: [PATCH] Formatting fixes for USAGE.md --- USAGE.md | 100 +++++++++++++++++++++++++++---------------------------- 1 file changed, 49 insertions(+), 51 deletions(-) diff --git a/USAGE.md b/USAGE.md index 7710db08e..6c2e4b418 100644 --- a/USAGE.md +++ b/USAGE.md @@ -1,4 +1,3 @@ - # Help Context-sensitive help is available for every command in `aws-vault`. @@ -14,10 +13,12 @@ $ aws-vault --help-long $ aws-vault exec --help ``` + ## Using aws-vault with multiple profiles -In addition to using IAM roles to assume temporary privileges as described in [README.md](./USAGE.md), aws-vault can also be used with multiple profiles directly. -This allows you to use multiple separate AWS accounts that have no relation to one another, such as work and home. +In addition to using IAM roles to assume temporary privileges as described in +[README.md](./USAGE.md), aws-vault can also be used with multiple profiles directly. This allows you +to use multiple separate AWS accounts that have no relation to one another, such as work and home. ```bash # Store AWS credentials for the "home" profile @@ -43,30 +44,30 @@ another_bucket ## Overriding the aws CLI to use aws-vault -You can create an overriding script (make it higher precedence in your PATH) that looks like the below: +If you want the `aws` command to use aws-vault automatically, you can create an overriding script +(make it higher precedence in your PATH) that looks like the below: ```bash #!/bin/bash -set -euo pipefail - -AWS_PROFILE="${AWS_DEFAULT_PROFILE:-work}" -exec aws-vault exec "$AWS_PROFILE" -- /usr/local/bin/aws "$@" +exec aws-vault exec "${AWS_DEFAULT_PROFILE:-work}" -- /usr/local/bin/aws "$@" ``` -The exec helps reduce the number of processes that are hanging around. The `$@` passes on the arguments from the wrapper to the original command. +The exec helps reduce the number of processes that are hanging around. The `$@` passes on the +arguments from the wrapper to the original command. ## Backends -You can choose different secret storage backends, which may be particularly useful on Linux, where you may prefer to use the system keyring with this environment variable: - -This can be specified on the command line with `aws-vault --backend=secret-service`, or by setting the environmental variable -```export AWS_VAULT_BACKEND=secret-service``` +You can choose different secret storage backends, which may be particularly useful on Linux, where +you may prefer to use the system keyring. This can be specified on the command line with +`aws-vault --backend=secret-service` or by setting the environment variable +`export AWS_VAULT_BACKEND=secret-service`. ## Listing profiles -You can use the `aws-vault list` command to list out the defined profiles, and any session associated with them. +You can use the `aws-vault list` command to list out the defined profiles, and any session +associated with them. ```bash $ aws-vault list @@ -78,9 +79,11 @@ work-read_only_role work work-admin_role work ``` + ## Removing profiles -The `aws-vault remove` command can be used to remove credentials. It works similarly to the `aws-vault add` command. +The `aws-vault remove` command can be used to remove credentials. It works similarly to the +`aws-vault add` command. ```bash # Remove AWS credentials for the "work" profile @@ -92,7 +95,6 @@ Deleted 1 sessions. `aws-vault remove` can also be used to close a session, leaving the credentials in place. - ```bash # Remove the session for the "work" profile, leaving the credentials in place $ aws-vault remove work --sessions-only @@ -102,8 +104,8 @@ Deleted 1 sessions. ## Logging into AWS console -You can use the `aws-vault login` command to open a browser window and login to AWS Console for a given account. - +You can use the `aws-vault login` command to open a browser window and login to AWS Console for a +given account: ```bash $ aws-vault login work ``` @@ -114,19 +116,17 @@ $ aws-vault login work **Careful**: this section is about a run mode that **lessens the security** given by default by aws-vault. It should be used only when there is a real reason to do so. -When you setup aws-vault, you give it your AWS Access Key. However, when running aws-vault, it -opens a temporary session and exposes this session's credentials rather than your original root +When you setup aws-vault, you give it your AWS Access Key. However, when running aws-vault, it opens +a temporary session and exposes this session's credentials rather than your original root credentials. Your actual credentials are in fact never exposed. Unfortunately, AWS enforces some limitations for connections opened using session credentials. One -of those limitations is that you cannot do a -[GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) +of those limitations is that you cannot do a [GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) action with such a connection. In the rare cases where being able to perform this action is needed, you'll have to tell aws-vault to run in a less secure mode and not give you a session, but rather expose the original credentials like so - ``` aws-vault exec work --no-session -- YOUR COMMAND ``` @@ -140,42 +140,40 @@ aws-vault exec work -- env | grep AWS ### Example use case -A common case is having a web application that uses AWS S3 as a file storage. This S3 -space is completely private for data privacy reasons. There is no public drop zone or whatever. When -clients of this application want to upload data to the service, they use an API to request temporary -access to S3. The application then uses AWS API to get a federation token, with specific IAM access -rights (typically can write only in a client specific location in the S3 bucket). The client can -then use those one-off temporary credentials with limited access to connect to S3 and drop some -files there. +A common case is having a web application that uses AWS S3 as a file storage. This S3 space is +completely private for data privacy reasons. There is no public drop zone or whatever. When clients +of this application want to upload data to the service, they use an API to request temporary access +to S3. The application then uses AWS API to get a federation token, with specific IAM access rights +(typically can write only in a client specific location in the S3 bucket). The client can then use +those one-off temporary credentials with limited access to connect to S3 and drop some files there. In such a situation, if you are running a local server, e.g. for dev, and want to call this API, then you can't use an AWS session, because AWS will return a 403 on the GetFederationToken operation. That is when you'll use the less secure solution described above. + ## Example ~/.aws/config -Here is an example ~/.aws/config file, to help show the configuation. -It defines two AWS accounts: "home" and "work", both of which use MFA. +Here is an example ~/.aws/config file, to help show the configuation. It defines two AWS accounts: +"home" and "work", both of which use MFA. The work account provides two roles, allowing the user to +become either profile. -The work account provides two roles, allowing the user to become either profile. +```ini +[profile home] +region = us-east-1 +mfa_serial = arn:aws:iam::IAM_ACCOUNTID:mfa/home-account -``` - [profile home] - region = us-east-1 - mfa_serial = arn:aws:iam::IAM_ACCOUNTID:mfa/home-account - - [profile work] - region = eu-west-1 - mfa_serial = arn:aws:iam::IAM_ACCOUNTID:mfa/work-account - - [profile work-read_only_role] - role_arn = arn:aws:iam::IAM_ACCOUNTID:role/read_only_role - source_profile = work - mfa_serial = arn:aws:iam::IAM_ACCOUNTID:mfa/work-account - - [profile work-admin_role] - role_arn = arn:aws:iam::IAM_ACCOUNTID:role/admin_role - source_profile = work - mfa_serial = arn:aws:iam::IAM_ACCOUNTID:mfa/work-account +[profile work] +region = eu-west-1 +mfa_serial = arn:aws:iam::IAM_ACCOUNTID:mfa/work-account + +[profile work-read_only_role] +role_arn = arn:aws:iam::IAM_ACCOUNTID:role/read_only_role +source_profile = work +mfa_serial = arn:aws:iam::IAM_ACCOUNTID:mfa/work-account +[profile work-admin_role] +role_arn = arn:aws:iam::IAM_ACCOUNTID:role/admin_role +source_profile = work +mfa_serial = arn:aws:iam::IAM_ACCOUNTID:mfa/work-account ```