Skip to content

Commit

Permalink
Formatting fixes for USAGE.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@mtibben
mtibben committed May 7, 2018
1 parent 2f27155 commit 7a69110
Showing 1 changed file with 50 additions and 58 deletions.
108 changes: 50 additions & 58 deletions USAGE.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

# Help

Context-sensitive help is available for every command in `aws-vault`.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -103,29 +102,27 @@ 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
```


## 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
Expand All @@ -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
```

0 comments on commit 7a69110

Please sign in to comment.