Update README.md

README.md

@@ -2,7 +2,7 @@
 
 AWS Vault is a tool to securely store and access AWS credentials in a development environment.
 
-AWS Vault stores IAM credentials in your operating system's secure keystore and then generates temporary credentials from those to expose to your shell and applications. It's designed to be complementary to the AWS CLI tools, and is aware of your [profiles and configuration in `~/.aws/config`](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files).
+AWS Vault stores IAM credentials in your operating system's secure keystore and then generates temporary credentials from those to expose to your shell and applications. It's designed to be complementary to the AWS CLI tools, and is aware of your [profiles and configuration in `~/.aws/config`](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-config-files).
 
 The supported backends are:
 
@@ -63,37 +63,64 @@ AWS_SESSION_TOKEN=%%%
 AWS_SECURITY_TOKEN=%%%
 ```
 
-Notice in the above environment how a session token gets written out. This is because `aws-vault` uses Amazon's STS service to generate [temporary credentials](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) via the `GetSessionToken` or `AssumeRole` API calls. These expire in a short period of time, so the risk of leaking credentials is reduced.
+Notice in the above environment how a session token gets written out. This is because `aws-vault` uses Amazon's STS service to generate [temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) via the `GetSessionToken` or `AssumeRole` API calls. These expire in a short period of time, so the risk of leaking credentials is reduced.
 
 The credentials are exposed to the subprocess in one of two ways:
 
  * Environment variables are written to the sub-process.
 
- * Local [EC2 Instance Metadata server](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) is started. This approach has the advantage that anything that uses Amazon's SDKs will automatically refresh credentials as needed, so session times can be as short as possible. The downside is that only one can run per host and because it binds to `169.254.169.254:80`, your sudo password is required.
+ * Local [EC2 Instance Metadata server](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) is started. This approach has the advantage that anything that uses Amazon's SDKs will automatically refresh credentials as needed, so session times can be as short as possible. The downside is that only one can run per host and because it binds to `169.254.169.254:80`, your sudo password is required.
 
 The default is to use environment variables, but you can opt-in to the local instance metadata server with the `--server` flag on the `exec` command.
 
 
 ### Assuming Roles
 
-Best-practice is to have a read-only account that you use on a day-to-day basis, and then use [IAM roles to assume temporary admin privileges](http://docs.aws.amazon.com/cli/latest/userguide/cli-roles.html) along with an MFA.
+[Best-practice is to create individual users](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users) for anyone who needs access to your AWS account, and [create Roles to delegate permissions](https://docs.aws.amazon.com/cli/latest/userguide/cli-roles.html).
 
-First you'll need to [setup an MFA token in the AWS Console](http://docs.aws.amazon.com/IAM/latest/UserGuide/GenerateMFAConfigAccount.html) and create a role with admin access.
+First you'll need to create the users and roles in IAM. Next, edit your `~/.aws/config` to add profiles with a `role_arn`. For example:
 
-Edit your `~/.aws/config` to add the `role_arn` and `mfa_serial` into a new profile:
+```ini
+[profile jonsmith]
+region = us-east-1
+
+[profile prod-readonly]
+region=us-east-1
+role_arn = arn:aws:iam::111111111111:role/ReadOnly
+source_profile = jonsmith
+
+[profile prod-admin]
+region=us-east-1
+role_arn = arn:aws:iam::111111111111:role/Administrator
+source_profile = jonsmith
+```
+
+Now when you use the `prod-admin` profile, `aws-vault` will look in the `jonsmith` profile's keychain for credentials and then use those credentials to assume the `Administrator` role.
+
+### Using MFA
+
+You should also require that users provide a one-time key generated from a multi-factor authentication (MFA) device when they attempt to make a call using the `prod-admin` profile.
+
+First you'll need to
+[setup an MFA device](https://docs.aws.amazon.com/IAM/latest/UserGuide/GenerateMFAConfigAccount.html). You can then [set up your IAM role to enforce MFA](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-mfa). Next, add a line to the role profile that specifies the ARN of the user's MFA device. For example:
 
 ```ini
-[profile prod]
+[profile jonsmith]
+region = us-east-1
+
+[profile prod-readonly]
 region=us-east-1
+role_arn = arn:aws:iam::111111111111:role/ReadOnly
+source_profile = jonsmith
 
 [profile prod-admin]
 region=us-east-1
 role_arn = arn:aws:iam::111111111111:role/Administrator
-mfa_serial = arn:aws:iam::222222222222:mfa/jonsmith
-source_profile = prod
+mfa_serial = arn:aws:iam::111111111111:mfa/jonsmith
+source_profile = jonsmith
 ```
 
-Then when you use the `prod-admin` profile, `aws-vault` will look in the `prod` profile's keychain for credentials and then use those credentials to assume the `Administrator` role. This assumed role is stored as a short duration session in your keychain so you will only have to enter MFA once per session.
+Now when you use the `prod-admin` profile `aws-vault` will prompt you for an MFA token. This assumed role's session is stored in your keychain so you will only have to enter your MFA once per session.
 
 ## macOS Code-signing
 
@@ -108,7 +135,7 @@ The [macOS release builds](https://github.com/99designs/aws-vault/releases) are
 
 If you are developing or compiling the aws-vault binary yourself, you can generate a self-signed code signing certificate.
 
-Check out Apple's guide on it [here](http://web.archive.org/web/20090119080759/http://developer.apple.com/documentation/Security/Conceptual/CodeSigningGuide/Procedures/chapter_3_section_2.html), or find it in `Keychain Access > Certificate Assistant > Create Certificate > Code Signing Certificate`.
+Check out Apple's guide on it [here](https://web.archive.org/web/20090119080759/http://developer.apple.com/documentation/Security/Conceptual/CodeSigningGuide/Procedures/chapter_3_section_2.html), or find it in `Keychain Access > Certificate Assistant > Create Certificate > Code Signing Certificate`.
 
 You can then sign your binary like this:
 
@@ -120,10 +147,10 @@ codesign -s "Name of my certificate" ./aws-vault
 ## References and Inspiration
 
  * https://github.com/pda/aws-keychain
- * http://docs.aws.amazon.com/IAM/latest/UserGuide/MFAProtectedAPI.html
- * http://docs.aws.amazon.com/IAM/latest/UserGuide/IAMBestPractices.html#create-iam-users
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/MFAProtectedAPI.html
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/IAMBestPractices.html#create-iam-users
  * https://github.com/paperg/awsudo
  * https://github.com/AdRoll/hologram
  * https://github.com/realestate-com-au/credulous
  * https://github.com/dump247/aws-mock-metadata
- * http://boto.readthedocs.org/en/latest/boto_config_tut.html
+ * https://boto.readthedocs.org/en/latest/boto_config_tut.html