From d5d8d0f8b99eaf5554cb0f5f95a21bbb485d2877 Mon Sep 17 00:00:00 2001
From: Michael Tibben <michael.tibben@99designs.com>
Date: Fri, 10 Mar 2023 20:53:36 +1100
Subject: [PATCH] Add typical use-cases to USAGE

---
 USAGE.md | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)

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