Browse the Repo

file-type-icon.circleci
file-type-icon.github
file-type-icon_ci
file-type-icon_docs
file-type-iconcodegen
file-type-iconexamples
file-type-iconmodules
file-type-icon_deprecated
file-type-iconauto-update
file-type-iconaws-auth
file-type-iconbin
file-type-iconAWS-AUTH-1PASSWORD.md
file-type-iconAWS-AUTH-LASTPASS.md
file-type-iconREADME.md
file-type-iconinstall.sh
file-type-iconaws-config-bucket
file-type-iconaws-config-multi-region
file-type-iconaws-config-rules
file-type-iconaws-config
file-type-iconaws-organizations
file-type-iconcloudtrail-bucket
file-type-iconcloudtrail
file-type-iconcross-account-iam-roles
file-type-iconcustom-iam-entity
file-type-iconebs-encryption-multi-region
file-type-iconebs-encryption
file-type-iconfail2ban
file-type-icongithub-actions-iam-role
file-type-iconguardduty-multi-region
file-type-iconguardduty
file-type-iconiam-access-analyzer-multi-region
file-type-iconiam-groups
file-type-iconiam-policies
file-type-iconiam-user-password-policy
file-type-iconiam-users
file-type-iconip-lockdown
file-type-iconkms-cmk-replica
file-type-iconkms-grant-multi-region
file-type-iconkms-master-key-multi-region
file-type-iconkms-master-key
file-type-iconntp
file-type-iconos-hardening
file-type-iconprivate-s3-bucket
file-type-iconsaml-iam-roles
file-type-iconsecrets-manager-resource-policies
file-type-iconssh-grunt-selinux-policy
file-type-iconssh-grunt
file-type-iconssh-iam
file-type-iconssm-healthchecks-iam-permissions
file-type-icontls-cert-private
file-type-icontest
file-type-icon.editorconfig
file-type-icon.gitignore
file-type-icon.pre-commit-config.yaml
file-type-iconCODEOWNERS
file-type-iconLICENSE.txt
file-type-iconREADME.adoc
file-type-iconterraform-cloud-enterprise-private-module-...

Browse the Repo

file-type-icon.circleci
file-type-icon.github
file-type-icon_ci
file-type-icon_docs
file-type-iconcodegen
file-type-iconexamples
file-type-iconmodules
file-type-icon_deprecated
file-type-iconauto-update
file-type-iconaws-auth
file-type-iconbin
file-type-iconAWS-AUTH-1PASSWORD.md
file-type-iconAWS-AUTH-LASTPASS.md
file-type-iconREADME.md
file-type-iconinstall.sh
file-type-iconaws-config-bucket
file-type-iconaws-config-multi-region
file-type-iconaws-config-rules
file-type-iconaws-config
file-type-iconaws-organizations
file-type-iconcloudtrail-bucket
file-type-iconcloudtrail
file-type-iconcross-account-iam-roles
file-type-iconcustom-iam-entity
file-type-iconebs-encryption-multi-region
file-type-iconebs-encryption
file-type-iconfail2ban
file-type-icongithub-actions-iam-role
file-type-iconguardduty-multi-region
file-type-iconguardduty
file-type-iconiam-access-analyzer-multi-region
file-type-iconiam-groups
file-type-iconiam-policies
file-type-iconiam-user-password-policy
file-type-iconiam-users
file-type-iconip-lockdown
file-type-iconkms-cmk-replica
file-type-iconkms-grant-multi-region
file-type-iconkms-master-key-multi-region
file-type-iconkms-master-key
file-type-iconntp
file-type-iconos-hardening
file-type-iconprivate-s3-bucket
file-type-iconsaml-iam-roles
file-type-iconsecrets-manager-resource-policies
file-type-iconssh-grunt-selinux-policy
file-type-iconssh-grunt
file-type-iconssh-iam
file-type-iconssm-healthchecks-iam-permissions
file-type-icontls-cert-private
file-type-icontest
file-type-icon.editorconfig
file-type-icon.gitignore
file-type-icon.pre-commit-config.yaml
file-type-iconCODEOWNERS
file-type-iconLICENSE.txt
file-type-iconREADME.adoc
file-type-iconterraform-cloud-enterprise-private-module-...
ssh-grunt

ssh-grunt

Manage SSH access to EC2 Instances using groups in AWS IAM or your Identity Provider (e.g., ADFS, Google, Okta, etc).

Code Preview

Preview the Code

mobile file icon

README.md

down

AWS Auth Helper

This module is a small wrapper script for the AWS CLI that makes it much easier to authenticate to AWS when:

  1. Multi-factor authentication (MFA) is enabled, and/or
  2. You want to assume an IAM Role, such as an IAM role that gives you access to another AWS account.

Motivation

Normally, if MFA is enabled, setting up your credentials as environment variables is a multi-step process. First, you make the call to fetch the temporary STS credentials:

aws sts get-session-token --serial-number arn:aws:iam::123456789011:mfa/jondoe --token-code 123456

Which returns a blob of JSON:

{
  "Credentials": {
    "AccessKeyId": "AAA",
    "SecretAccessKey": "BBB",
    "SessionToken": "CCC",
    "Expiration": "DDD"
  }
}

Next, you have to copy and paste each part of that JSON output into the proper environment variable:

export AWS_ACCESS_KEY_ID='AAA'
export AWS_SECRET_ACCESS_KEY='BBB'
export AWS_SESSION_TOKEN='CCC'
export AWS_SESSION_EXPIRATION='DDD'

If you want to assume an IAM role, you have to make another API call:

aws sts assume-role --role-arn arn:aws:iam::123456789011:role/my-role --role-session-name my-name 

Which returns another blob of JSON:

{
  "Credentials": {
    "AccessKeyId": "EEE",
    "SecretAccessKey": "FFF",
    "SessionToken": "GGG",
    "Expiration": "HHH"
  }
}

Which you again have to copy into the proper environment variable:

export AWS_ACCESS_KEY_ID='EEE'
export AWS_SECRET_ACCESS_KEY='FFF'
export AWS_SESSION_TOKEN='GGG'
export AWS_SESSION_EXPIRATION='HHH'

With this script, all of this can be done in a single command!

Quick start

Install aws-auth

To install the script, you can either copy it manually to a location on your PATH or use the gruntwork-install command:

gruntwork-install --module-name 'aws-auth' --repo 'https://github.com/gruntwork-io/terraform-aws-security' --tag 'v0.6.5'

Usage

WARNING! Before running the following commands, authenticate to the AWS account that contains your IAM User using your static API Access Key ID and Secret Key.

We strongly recommend using a password manager like 1Password or pass to store any static credentials so they don't sit unencrypted on your local disk. Internally, the Grunts at Gruntwork use pass with a unique GPG Key for each set of secrets.

Authenticate to an AWS Account using MFA

aws-auth --serial-number arn:aws:iam::123456789011:mfa/jondoe --token-code 123456

Find the Serial Number ARN by viewing your IAM User profile in the AWS web console.

Authenticate to an AWS Account using MFA and Assume an IAM Role in another Account

aws-auth --serial-number arn:aws:iam::123456789011:mfa/jondoe --token-code 123456 --role-arn arn:aws:iam::123456789011:role/my-role

Assume an IAM Role in another Account and configure the credentials to not expire for 12 hours

aws-auth --serial-number arn:aws:iam::123456789011:mfa/jondoe --token-code 123456 --role-arn arn:aws:iam::123456789011:role/my-role --role-duration-seconds 43200

Required IAM Policy

You must have the iam:AssumeRole permission on the "primary" AWS account in order to assume an IAM Role in a "secondary" AWS account. Furthermore, you must have the iam:AssumeRole permission on the specific IAM Role you wish to assume or on all resources (*).

Wrap the output in eval()

When finished running, the aws-auth script will write a series of export XXX=YYY statements to stdout:

aws-auth --serial-number arn:aws:iam::123456789011:mfa/jondoe --token-code 123456

export AWS_ACCESS_KEY_ID='AAA'
export AWS_SECRET_ACCESS_KEY='BBB'
export AWS_SESSION_TOKEN='CCC'
export AWS_SESSION_EXPIRATION='DDD'

NOTE: AWS_SESSION_EXPIRATION environment variable is not used by any official libraries (i.e. aws cli, boto, etc.). It's only exported for your convenience, for example a wrapper that renews once expired.

To setup your AWS environment variables in one command, all you have to do is eval the result!

eval "$(aws-auth --serial-number arn:aws:iam::123456789011:mfa/jondoe --token-code 123456)"

Switching Between multiple accounts

A typical account switching workflow might be:

  1. Authenticate to "primary" AWS account using static credentials
  2. Use aws-auth to authenticate to "dev" account.
  3. Authenticate to "primary" AWS account using static credentials
  4. Use aws-auth to authenticate to "prod" account.

Notice that you must re-authenticate to the "primary" AWS account before you can use aws-auth again.

Combining it with password managers

To be fair, using aws-auth isn't really a one-liner, since you have to set your permanent AWS credentials first:

export AWS_ACCESS_KEY_ID='<PERMANENT_ACCESS_KEY>'
export AWS_SECRET_ACCESS_KEY='<PERMANENT_SECRET_KEY>'
eval $(aws-auth --serial-number arn:aws:iam::123456789011:mfa/jondoe --token-code 123456)

If you store your secrets in a CLI-friendly password manager, such as pass, lpass or 1Password CLI, then you can reduce this even further! Instructions on how to set this up for Lastpass / lpass can be found here and 1Password / op here.

First, store your permanent AWS credentials in pass:

pass insert aws-access-key-id
Enter password for aws-access-key-id: <PERMANENT_ACCESS_KEY>

pass insert aws-secret-access-key
Enter password for aws-secret-access-key: <PERMANENT_SECRET_KEY>

Next, store your MFA ARN in pass as well:

pass insert aws-mfa-arn
Enter password for aws-mfa-arn: arn:aws:iam::123456789011:mfa/jondoe

If you will be assuming an IAM Role ARN, put that in pass too:

pass insert aws-iam-role-arn
Enter password for aws-iam-role-arn: arn:aws:iam::123456789011:role/my-role

Now, you can store a script in pass that ties all of this together. Run the insert command with the -m parameter so you can enter multiple lines:

pass insert -m aws-sts-env-vars
Enter contents of aws-sts-env-vars and press Ctrl+D when finished:

And now enter the following script:

read -p "Enter your MFA token: " token
eval $(AWS_ACCESS_KEY_ID=$(pass aws-access-key-id) AWS_SECRET_ACCESS_KEY=$(pass aws-secret-access-key) aws-auth --serial-number $(pass aws-mfa-arn) --token-code "$token")

Using Fish Shell? Use the following modified script instead:

# For Fish Shell users only
echo "Enter your token:";
read -p "" token;
eval (export AWS_ACCESS_KEY_ID=(pass aws-access-key-id); export AWS_SECRET_ACCESS_KEY=(pass lotus/aws-secret-access-key); aws-auth --serial-number (pass aws-mfa-arn) --token-code "$token")

If you want the script to assume an IAM role, just add the --iam-role parameter at the end:

read -p "Enter your MFA token: " token
eval $(AWS_ACCESS_KEY_ID=$(pass aws-access-key-id) AWS_SECRET_ACCESS_KEY=$(pass aws-secret-access-key) aws-auth --serial-number $(pass aws-mfa-arn) --token-code "$token" --role-arn $(pass aws-iam-role-arn))

Now, to setup your temporary STS credentials is truly a one-liner!

eval "$(pass aws-sts-env-vars)"

Note: the double quotes around the $() are required.

Running the script with a cronjob

If you you need to run aws-auth with a cronjob, you may want to set the $USER env variable to your local user:

  • e.g. set the $USER variable like so: 05 10 * * * env USER=$USERNAME /path/to-your-script/script

Questions? Ask away.

We're here to talk about our services, answer any questions, give advice, or just to chat.

Ready to hand off the Gruntwork?