diff --git a/USAGE.md b/USAGE.md index 472575b03..14c0f2f80 100644 --- a/USAGE.md +++ b/USAGE.md @@ -2,6 +2,11 @@ - [Usage](#usage) - [Getting Help](#getting-help) + - [Typical use-cases for aws-vault](#typical-use-cases-for-aws-vault) + - [Use-case 1: aws-vault is the executor and provides the environment](#use-case-1-aws-vault-is-the-executor-and-provides-the-environment) + - [Use-case 2: aws-vault is a "master credentials vault" for AWS SDK](#use-case-2-aws-vault-is-a-master-credentials-vault-for-aws-sdk) + - [Use-case 3: aws-vault is a "MFA session cache" for AWS SDK](#use-case-3-aws-vault-is-a-mfa-session-cache-for-aws-sdk) + - [Use-case 4: aws-vault caches alternative credential sources](#use-case-4-aws-vault-caches-alternative-credential-sources) - [Config](#config) - [AWS config file](#aws-config-file) - [`include_profile`](#include_profile) @@ -57,6 +62,106 @@ $ aws-vault --help-long $ aws-vault exec --help ``` +## Typical use-cases for aws-vault + +There are a few different ways aws-vault can be used + +### Use-case 1: aws-vault is the executor and provides the environment + +Use aws-vault exclusively as a command executor, where aws-vault provides the environment and runs a command. + +```ini +[profile my_profile_master] +# master credentials stored in aws-vault + +[profile my_profile_role] +source_profile=my_profile_master +role_arn=xxx +``` + +```bash +aws-vault exec my_profile_master ./my-command # success, uses sts session generated by aws-vault +aws-vault exec my_profile_role ./my-command # success, uses role creds generated by aws-vault + +AWS_PROFILE=my_profile_master ./my-command # Not expected to be functional +AWS_PROFILE=my_profile_role ./my-command # Not expected to be functional +``` + +In this scenario, the profile name and aws config is used exclusively by aws-vault, which provides the environment for the command to run in. + +This is a very unix-y and 12-factor approach. It's the original and the primary use-case of aws-vault - it's why `aws-vault exec` exists. + + +### Use-case 2: aws-vault is a "master credentials vault" for AWS SDK + +aws-vault can be used in `credential_process` in the AWS config to provide master creds. This is more in-line with the AWS SDK way of approaching the problem via `credential_process` and `AWS_PROFILE` + +```ini +[profile my_profile_master] +credential_process = aws-vault export --format=json --no-session my_profile_master + +[profile my_profile_role] +source_profile=my_profile_master +role_arn=xxx +``` + +```bash +aws-vault exec my_profile_master ./my-command # success (uses master creds) +aws-vault exec my_profile_role ./my-command # success (aws-vault role) + +AWS_PROFILE=my_profile_master ./my-command # success (uses credential_process to get aws-vault master creds) +AWS_PROFILE==my_profile_role ./my-command # success (SDK role) +``` + +### Use-case 3: aws-vault is a "MFA session cache" for AWS SDK + +Very similar to Use-case 2, aws-vault can be used to cache STS MFA credentials between profiles. This means you are not forced to re-authenticate with MFA every time you switch profiles + +```ini +[profile my_profile_master] +mfa_serial=mmm +credential_process = aws-vault export --format=json my_profile_master + +[profile my_profile_role] +source_profile=my_profile_master +mfa_serial=mmm +role_arn=xxx1 + +[profile my_profile_role2] +source_profile=my_profile_master +mfa_serial=mmm +role_arn=xxx2 +``` + +```bash +aws-vault exec my_profile_master ./my-command # Not expected to be functional +aws-vault exec my_profile_role ./my-command # Not expected to be functional + +AWS_PROFILE=my_profile_master ./my-command # success (uses credential_process to get aws-vault session) +AWS_PROFILE=my_profile_role ./my-command # success (uses aws-vault session + SDK role) +``` + + +### Use-case 4: aws-vault caches alternative credential sources + +aws-vault caches credentials from alternative credential sources like `sso_start_url`, `web_identity_token_process`, `credential_process` + +```ini +[profile my_profile_using_sso] +sso_start_url = https://mycompany.awsapps.com/start + +[profile my_profile_using_process] +credential_process = my-custom-creds-cmd +``` + +```bash +aws-vault exec my_profile_using_sso ./my-command # success, uses aws-vault caching +aws-vault exec my_profile_using_process ./my-command # success, uses aws-vault caching + +AWS_PROFILE=my_profile_using_sso ./my-command # success, no caching +AWS_PROFILE=my_profile_using_process ./my-command # success, no caching +``` + ## Config