From 7a691107044ac5909068ff1ac8dca02d6216229a 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 | 108 ++++++++++++++++++++++++++----------------------------- 1 file changed, 50 insertions(+), 58 deletions(-) diff --git a/USAGE.md b/USAGE.md index 7710db08e..7586ce676 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,25 +44,23 @@ 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 @@ -78,6 +77,7 @@ 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. @@ -92,7 +92,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 @@ -103,7 +102,6 @@ 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. - ```bash $ aws-vault login work ``` @@ -111,21 +109,20 @@ $ aws-vault login work ## Not using session credentials -**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. +**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 -credentials. Your actual credentials are in fact never exposed. +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) -action with such a connection. +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) 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 +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 +137,37 @@ 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. +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 ```