Repository files navigation

This repository is no longer maintained.

Assume IAM roles through anAWS Bastion account withMFA orSAML Provider via the command line.

AWS Bastion accounts store only IAM users providing a central, isolated account to manage their credentials and access. Trusting AWS accounts create IAM roles that the Bastion users can assume, to allow a single user access to multiple accounts resources. Under this setup,assume-role makes it easier to follow the standard security practices of MFA and short lived credentials.

SAML Providers allow you to use federated login to assume-role-with-saml. SAML Assertions should beformatted as followingaccording to AWS.

assume-role requiresjq andaws CLI tools to be installed.

brew tap coinbase/assume-rolebrew install assume-role

You can then upgrade at any time by running:

brew upgrade assume-role

You can install/upgrade assume-role with this command:

curl https://raw.githubusercontent.com/coinbase/assume-role/master/install-assume-role -Ocat install-assume-role# inspect the script for securitybash ./install-assume-role# install assume-role

It will ask for your sudo password if necessary.

If you are using a bastion setup (the default), make sure that credentials for your AWS bastion account are stored in~/.aws/credentials.

Out of the box you can callassume-role like:

eval$(assume-role account-id role mfa-token)

If your shell supports bash functions (e.g. zsh) then you can addsource $(which assume-role) to yourrc file (e.g.~/.zshrc), then you can callassume-role like:

assume-role [account-id] [role] [mfa-token]

assume-role this method can be used with arguments or interactively like:

If you would like to authenticate with your SAML provider using username and password instead, add this to your.bash_profile or.bashrc:

export AWS_ASSUME_ROLE_AUTH_SCHEME=saml # defaults to bastionexport SAML_IDP_ASSERTION_URL="your saml idp assertion url"export SAML_IDP_NAME="Name of your IdP registerd with AWS"# This is an example body template.export SAML_IDP_REQUEST_BODY_TEMPLATE='{"service": "aws", "email": "$saml_user", "password": "$saml_password"}'

The URL should serve a POST API that returns a SAML Assertion under thesaml_response JSON key.

You can specify your JSON body via an envar that uses thesaml_user andsaml_password envars. You can specify any body template you want.

Your service should be hosted over SSL since credentials might be sent in the response, depending on your JSON body implementation.You could hash the password client-side if you wish to do so in the template envar

The script will warn you if you are not serving over SSL.

Once you assume-role, you will be prompted for your SAML credentials (username and password).

If you would like to store your credentials on the filesystem for ease of use, you can create a~/.saml/credentials file.

An example of what this looks like is (example syntax; These arenot real):

username = lukeskywalkerpassword = hunter2

You can define aliases to account ids in~/.aws/accounts which assume-role can use, e.g.

{"default":"123456789012","staging":"123456789012","production":"123456789012"}

With this file, to assume theread role in theproduction account:

assume-role productionread# ORassume-role 123456789012read

Also, by setting$AWS_PROFILE_ASSUME_ROLE, you can define a default profile forassume-role if you want to separate concerns betweendefault accounts forassume-role and vanillaawscli or simply to have better names thandefault:

$export AWS_PROFILE_ASSUME_ROLE="bastion"$ assume-role productionread

Moreover, if you are in the need oflonger client-side assume-role sessions and don't want toenter your MFA authentication every hour (default) this one is for you:

$export AWS_ROLE_SESSION_TIMEOUT=43200

However, be aware that forchained roles there's currently a forced1 hour limit from AWS. You'll get the following error if you exceed that specific limit:

DurationSeconds exceeds the 1 hour session limit for roles assumed by role chaining.

You can also override the AWS IAM username which is usually fetched from the AWS IAM get-user api. This might not be allowed in some environments though:

$export AWS_USERNAME=my_username

Here is a simple example of how to set up aBastion AWS account with an id0987654321098 and aProduction account with the id123456789012.

In theProduction account create a role calledread, with the trust relationship:

{"Statement": [    {"Effect":"Allow","Principal": {"AWS":"arn:aws:iam::0987654321098:root"      },"Action":"sts:AssumeRole","Condition": {"Bool": {"aws:SecureTransport":"true","aws:MultiFactorAuthPresent":"true"        },"NumericLessThan": {"aws:MultiFactorAuthAge":"54000"        }      }    }  ]}

The conditionsaws:MultiFactorAuthPresent andaws:MultiFactorAuthAge forces the use of temporary credentials secured with MFA.

In theBastion account, create a group calledassume-read with the policy:

{"Statement": [    {"Effect":"Allow","Action": ["sts:AssumeRole" ],"Resource": ["arn:aws:iam::123456789012:role/read" ],"Condition": {"Bool": {"aws:MultiFactorAuthPresent":"true","aws:SecureTransport":"true"        },"NumericLessThan": {"aws:MultiFactorAuthAge":"54000"        }      }    }  ]}

Attach this group toBastion users that should be able useread's policies in theProduction account.

You can assume theread role inProduction by running:

assume-role 123456789012 read

Then entering a MFA token on request.

The SAML Provider will need to be registered in the same AWS account that you are doing assume-role-with-saml into. If you are dealing with many accounts,the suggested way to handle this is to have one deployment of your SAML Provider that returns assertions for several accounts/roles using the registeredSAML Provider ARN and the role ARN.

Here is a simple example of how to set up aSAML Provider in aProduction account with the id123456789012.

In theProduction account create a saml provider calledsaml-idp, and a role calledread with the trust relationship:

{"Statement": [    {"Effect":"Allow","Principal": {"Federated":"arn:aws:iam::123456789012:saml-provider/saml-idp"      },"Action":"sts:AssumeRoleWithSAML","Condition": {"Bool": {"aws:SecureTransport":"true",        },"StringEquals": {"SAML:aud":"https://signin.aws.amazon.com/saml"        }      }    }  ]}

And configure your SAML Provider to return signed assertions for theread role in theProduction acount.

If you are usingzsh you can get a sweet prompt by adding to your.zshrc file:

# AWS ACCOUNT NAMEfunctionaws_account_info {  ["$AWS_ACCOUNT_NAME" ]&& ["$AWS_ACCOUNT_ROLE" ]&&echo"%F{blue}aws:(%f%F{red}$AWS_ACCOUNT_NAME:$AWS_ACCOUNT_ROLE%f%F{blue})%F$reset_color"}# )ofni_tnuocca_swa($ is $(aws_account_info) backwardsPROMPT=`echo$PROMPT| rev| sed's/ / )ofni_tnuocca_swa($ /'| rev`

Forbash you could put the following in your.bash_profile file:

functionaws_account_info {  ["$AWS_ACCOUNT_NAME" ]&& ["$AWS_ACCOUNT_ROLE" ]&&echo -n"aws:($AWS_ACCOUNT_NAME:$AWS_ACCOUNT_ROLE)"}PROMPT_COMMAND='aws_account_info'

assume-role is tested withBATS (Bash Automated Testing System). To run the tests first you will needbats,jq andshellcheck installed. On macOS this can be accomplished withbrew:

brew install batsbrew install jqbrew install shellcheck

Then runbats test/assume-role.bats;