diff --git a/README.md b/README.md index 4fe1d4039..00c93ef68 100644 --- a/README.md +++ b/README.md @@ -76,24 +76,51 @@ The default is to use environment variables, but you can opt-in to the local ins ### 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](http://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](http://docs.aws.amazon.com/IAM/latest/UserGuide/GenerateMFAConfigAccount.html). You can then [set up your IAM role to enforce MFA](http://docs.aws.amazon.com/cli/latest/userguide/cli-roles.html) using `"Condition": { "Bool": { "aws:multifactorAuthPresent": true } }`. 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