bug fixes, updates documentation

README.md

@@ -1,3 +1,3 @@
 # AWSume: AWS Assume Made Awesome
 
-Awsume v4 is a work in progress.
+Check out the documentation at [awsu.me](https://awsu.me)!

awsume/awsumepy/default_plugins.py

@@ -199,7 +199,7 @@ def post_add_arguments(config: dict, arguments: argparse.Namespace, parser: argp
         kill(arguments)
         exit(0)
 
-    if arguments.role_arn and not arguments.role_arn.startswith('arn:aws:iam::'):
+    if arguments.role_arn and not arguments.role_arn.startswith('arn:'):
         logger.debug('Using short-hand role arn syntax')
         parts = arguments.role_arn.split(':')
         if len(parts) != 2:

docs/.vuepress/config.js

@@ -60,6 +60,13 @@ module.exports = {
           '/plugins/catch-exceptions',
         ],
       },
+      {
+        title: 'Updating to v4',
+        collapsable: true,
+        children: [
+          '/updating-v4/',
+        ],
+      },
       {
         title: 'Troubleshooting',
         collapsable: true,

docs/advanced/autoawsume.md

@@ -4,4 +4,4 @@ When you installed awsume, you may have noticed you also got an `autoawsume` com
 
 To start auto-refreshing credentials, use the `-a`/`--auto-refresh` flag. This will tell awsume to spin off `autoawsume` in the background to handle refreshing those credentials. Instead of putting your credentials into your environment variables, it'll create a new profile in your credentials file prefixed with `autoawsume-`. It will also export the `AWS_PROFILE` and `AWS_DEFAULT_PROFILE` environment variables to point to the newly created profile.
 
-Autoawsume will look for when the soonest expiring profile will expire and wait until then, when it will re-execute awsume to refresh the credentials in the background, so you don't have to worry about needing to re-awsume your profile's credentials.
+Autoawsume will look for when the earliest expiring profile will expire and wait until then, when it will re-execute awsume to refresh the credentials in the background, so you don't have to worry about needing to re-awsume your profile's credentials. It will continue to repeat this process until it cannot refresh credentials anymore (either the source_profile credentials expired or the user has requested to stop autoawsume with an `awsume -k`).

docs/general/overview.md

@@ -20,6 +20,21 @@ Awsume works by setting a number of environment variables in your shell. These a
 - `AWS_REGION`
 - `AWS_DEFAULT_REGION`
 
+## Terminology
+
+- **role profile** is a profile that contains a `role_arn` property, and either a `source_profile` or `credential_source` property.
+- **non-role profile** / **user profile** is a profile that does not have a `role_arn` property. It is typically a profile that has access keys for a user. However it can also refer to profiles that have temporary session token credentials in them, which may or may not be role credentials.
+
 ## Awsume vs Awsumepy
 
 Because awsume requires the ability to manage your current shell's environment variables, it must be sourced (unless you're running on Windows). On unix-like systems, a subshell cannot update a parent shell's environment variables. Unfortunately, you cannot `source` a python script, so awsume is architected with a shell wrapper (awsume) around a python script (awsumepy).
+
+When given a role profile that uses a source_profile which requires MFA, awsume will make the `get-session-token` call with the source_profile to get 12-hour long credentials. It will then cache those MFA-authenticated credentials. Then it will make the `assume-role` call to get credentials for the requested amount of time (AWS has a default of 1 hour maximum role credentials). When those role credentials run out, you can re-execute awsume, and awsume will use those cache'd MFA-authenticated credentials to get new role credentials for you, without re-prompting you for your MFA token. This can be automated with [autoawsume](/advanced/autoawsume), but this is the typical use-case for awsume.
+
+If you give awsume a non-role profile that doesn't require MFA (no `mfa_serial`), it will simply export those credentials found in the profile.
+
+If you give awsume a non-role profile that does require MFA, it will check the cache for the profile's credentials, and if the cache'd credentials either don't exist or are expired, it will make the get-session-token call to get new ones and cache those to. However if the cache exists and is valid, it'll use those credentials without prompting for MFA.
+
+When assuming a role, awsume will set the session name to the profile name you gave awsume, however this can be changed with `--session-name` (see the [usage](/general/usage) for more details).
+
+Awsume uses the `~/.awsume/cache/` directory to store cache'd credentials. It stores credentials by access key ID, so the case multiple profiles have the same access keys, it'll be cached the same.

docs/general/usage.md

@@ -168,7 +168,37 @@ Or you can reset to the default value with:
 awsume --config reset role-duration
 ```
 
-The configuration is stored in the `~/.awsume/config.json` file.
+You can delete a value with:
+
+```
+awsume --config clear role-duration
+```
+
+And you can get complex with your config like this:
+
+```yaml
+# awsume --config set a.b.c x '{"hello":"world"}' 1 '"2"'
+a:
+  b:
+    c:
+     - 'x'
+     - hello: world
+     - 1
+     - '2'
+```
+
+For each value, if it can be parsed as JSON, it will be. Otherwise it will be a string.
+
+If you only provide one value, it will set the key to that value directly, without nesting it in an array, as follows:
+
+```yaml
+# awsume --config set a.b.c x
+a:
+  b:
+    c: x
+```
+
+The configuration is stored in the `~/.awsume/config.yaml` file.
 
 ## List Plugins
 

docs/plugins/get-credentials.md

@@ -42,7 +42,7 @@ def get_credentials(config: dict, arguments: argparse.Namespace, profiles: dict)
 
 ## `get_credentials_with_saml`
 
-This hook will only be called when awsuem is given the `--with-saml` flag, and will prevent other `get_credentials...` hooks from being called.
+This hook will only be called when awsuem is given the `--with-saml` flag, and will prevent other `get_credentials...` hooks from being called. If there is only one role provided in the assertion, it will be used. If there are multiple and `--role-arn` is provided to awsume, it will use the closest match. If there are multiple and `--role-arn` is not provided, it will prompt the user for which role to use.
 
 ### Parameters
 
@@ -52,15 +52,10 @@ This hook will only be called when awsuem is given the `--with-saml` flag, and w
 
 ### Returns
 
-- A `dict` of aws credentials in the following format:
+- A `str` of the saml assertion:
 
 ```python
-{
-  'AccessKeyId': '',
-  'SecretAccessKey': '',
-  'SessionToken': '',
-  'Region': '',
-}
+'PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZ...3NhbWwycDpSZXNwb25zZT4='
 ```
 
 ### Example

docs/updating-v4/index.md

@@ -0,0 +1,31 @@
+# Updating to Awsume Version 4
+
+Awsume v4 does things a little differently than previous versions. This guide should help you if you're updating awsume from an earlier version.
+
+::: warning
+If you run into any issues, feel free to [open an issue](https://github.com/trek10inc/awsume/issues/new)!
+:::
+
+## Plugin System
+
+Awsume changed plugin systems. Where we previously used [Yapsy](https://pypi.org/project/Yapsy/) we're now using [Pluggy](https://pluggy.readthedocs.io/en/latest/).
+
+Awsume used to store plugins in your home directory: `~/.aws/awsumePlugins`. This is no longer the case. Plugins are now actual python packages, installed via `pip` or some other python package installer. For this reason, you no longer need the `~/.aws/awsumePlugins` directory, so this can be emptied and deleted.
+
+## Login Profile Cleanup
+
+Awsume now _correctly_ prioritizes bash login files. There was a consistent bug in previous versions that would place the alias and autocomplete script definitions in the `~/.bashrc`, even in OS X (where the `~/.bashrc` is not loaded on login by default), causing awsume to not "just work." The awsume post-install configuration will now prioritize the `~/.bash_profile` over the `~/.bashrc` (read more about that [here](https://www.gnu.org/software/bash/manual/html_node/Bash-Startup-Files.html)). For this reason you might see doubling of the alias/autocomplete definitions, so you can clean up the unused ones.
+
+## Autocomplete script
+
+Related to login profile cleanup, the autocomplete script has changed. This is due to a refactor that migrated all autocomplete code out of awsume's core and made use of [fastentrypoints](https://pypi.org/project/fastentrypoints/), so that autocomplete would execute faster. So if you see multiple, _slightly different_ autocomplete script definitions for awsume, make sure to keep the one that has the `awsume-autocomplete` command.
+
+## Cache and Config
+
+Awsume now makes use of an `~/.awsume/` directory for storing cache and config. This means that you can migrate your settings from `~/.aws/awsume.json` to `~/.awsume/config.yaml`.
+
+Awsume will now no longer use the `~/.aws/cli/cache/` directory for it's own caching, so you can clear out all of those old awsume cache files.
+
+## Awsume configuration
+
+If anything went wrong with awsume's installation, you can now run the configuration commands outside of `pip install` with `awsume-configure`. Read more about it [here](/utilities/awsume-configure).