README.md in aws_assume_role-1.0.4 vs README.md in aws_assume_role-1.0.5

- old
+ new

@@ -7,11 +7,11 @@ aws-assume-role is a utility intended for developer and operator environments who need to use 2FA and role assumption to access AWS services. aws-assume-role can store both AWS access keys and ephemeral session tokens in -OS credential vaults - Keychain on OSX and Seahorse on Gnome. +OS credential vaults - Keychain on OSX and Keyring on Gnome. Why? --- This keeps your credentials safe in the keystore, and exist as @@ -43,11 +43,11 @@ Gnome Keyring uses the [GirFFI](https://github.com/mvz/gir_ffi) bindings, which require introspection bindings as well as Gnone Keyring, by installing one of the following packages: ``` sh # Debian/Ubuntu -apt-get install gnome-keyring libgirepository1.0-dev +apt-get install gnome-keyring libgirepository1.0-dev libgnome-keyring-common libgnome-keyring-dev # Fedora dnf install gobject-introspection-devel # CentOS @@ -63,26 +63,26 @@ aws-assume-role works best if you also store permanent credentials in your keystore: ``` sh > aws-assume-role configure Enter the profile name to save into configuration -company-sso +company_sso Enter the AWS region you would like to default to: eu-west-1 Enter the AWS Access Key ID to use for this profile: 1234567890010 Enter the AWS Secret Access Key to use for this profile: abcdefghijklmnopqrstuvwzyx1 -Profile `company-sso` saved to '/home/growthsmith/.aws/config' +Profile `company_sso` saved to '/home/growthsmith/.aws/config' ``` ### Configuring roles Now that you've set up permanent credentials in your OS credential store, you can now set up a role that you will assume in every day use: ``` sh -> aws-assume-role configure role -p company-dev --source-profile company-sso \ +> aws-assume-role configure role -p company-dev --source-profile company_sso \ --role-arn=arn:aws:iam::000000000001:role/ViewEC2 --role-session-name=growthsmith \ --mfa-serial automatic ``` `--mfa-serial automatic` will look up your default attached multi-factor device, but you can specify a specific ARN. @@ -99,21 +99,32 @@ This allows developers to call AWS through aws-assume-role, providing an MFA token without prompting for user input. To use this specify `--yubikey-oath-name` when calling configure role. ``` sh -> aws-assume-role configure role -p company-dev --source-profile company-sso \ +> aws-assume-role configure role -p company-dev --source-profile company_sso \ --role-arn=arn:aws:iam::000000000001:role/ViewEC2 --role-session-name=growthsmith \ ---mfa-serial automatic --yubikey-oath-name "Amazon Web Services:myuser@company-sso" +--mfa-serial automatic --yubikey-oath-name "Amazon Web Services:myuser@company_sso" ``` _Yubikey Support_: `aws-assume-role` uses the [smartcard gem](https://rubygems.org/gems/smartcard) to connect to the Yubikey, this itself depends upon some C libraries being installed. They provide [platform specific instructions](https://github.com/costan/smartcard/blob/master/BUILD#L19) for installing these libraries PC/SC. +Testing a profile +----------------- +You can test a profile using +```sh +> aws-assume-role test -p company_sso +Logged in as: + User: 9999999999 + Account: arn:aws:iam::3333333333:user/username + ARN: AIDAIOSWINGTB +``` + Running applications -------------------- You can run another application using @@ -130,29 +141,38 @@ ``` Please provide an MFA token 000000 ``` +Listing available profiles +-------------------------- +Configured profiles can be listed: +```sh +> aws-assume-role list +company_sso +company2_sso +company3_sso +``` Deleting a profile ------------------ If a set of credentials key needs revoking, or the profile isn't relevant anymore: ``` sh -> aws-assume-role delete -p company-sso -Please type the name of the profile, i.e. company-sso , to continue deletion. -company-sso -Profile company-sso deleted +> aws-assume-role delete -p company_sso +Please type the name of the profile, i.e. company_sso , to continue deletion. +company_sso +Profile company_sso deleted ``` Migrating AWS CLI profiles ------------------ It's better to revoke the existing keys and generate new ones. We try to overwrite the plaintext configuration file with random data, but this does not take care of ~/.aws/credentials and does not account for SSD wear levelling or copy-on-write snapshots. ``` -aws-assume-role migrate -p company-sso -Profile 'company-sso' migrated to keyring. +aws-assume-role migrate -p company_sso +Profile 'company_sso' migrated to keyring. ``` Exporting environment variables ------------------------------- You can use a session token in your shell any supported application without using @@ -182,10 +202,10 @@ --------------------- Given that `aws-assume-role` has knowledge of your role ARNs via AWS CLI profiles, you can get to the AWS console for that role/account using ``` sh -> aws-assume-role console -p company-sso +> aws-assume-role console -p company_sso ``` `aws-assume-role` will first attempt to log in and get a federated UI link, and otherwise fall back to the "switch role" page.