Skip to content

An aws-cli plugin that loads IAM Role credentials into environment variables

License

Notifications You must be signed in to change notification settings

hashbrowncipher/aws-roleshell

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

15 Commits
 
 
 
 
 
 
 
 

Repository files navigation

aws-roleshell

An aws-cli plugin that loads IAM Role credentials into environment variables. This plugin retrieves credentials using sts:AssumeRole, sets the equivalent environment variables, and then executes a wrapped command. This plugin is designed to serve as an adapter for software which is not capable of assuming a role by itself.

Usage is like so:

$ aws --profile readonly roleshell -- mycommand

In the above example, mycommand will run with IAM role credentials defined by the readonly profile.

Or you could load the appropriate environment variables into your shell by invoking roleshell without arguments:

$ eval $(aws --profile readonly roleshell)

Lastly, you can execute a new copy of your current shell, in which the new role will be assumed:

$ aws --profile readonly roleshell --shell

aws-roleshell makes use of the aws-cli temporary credentials cache, so multiple roleshells can re-use the same temporary credentials until they expire. This is especially useful for IAM roles that require MFA, because an MFA token is only required once per hour (by default), no matter how many shells are launched.

install

After installing this egg into your $PYTHONPATH, add the following into your ~/.aws/config:

[plugins]
roleshell = aws_roleshell

Or paste this into your terminal:

cat<<EOF >> ~/.aws/roleshell
[plugins]
roleshell = aws_roleshell
EOF

usage

Configure an IAM Role based aws-cli profile. The documentation should assist you, but here's an example to save you some reading:

$ cat<<EOF >> ~/.aws/credentials

[readonly]
role_arn = arn:aws:iam::123456789012:role/readonly
mfa_serial = arn:aws:iam::123456789012:mfa/myuser
source_profile = default
EOF

After loading credentials, aws roleshell will launch whatever command you specify on the command line. If no command is given, roleshell will output shell-compatible variable exports for use with eval.

$ aws ec2 describe-instances # runs as 'user/myuser'
$ eval $(aws --profile readonly roleshell)
Enter MFA code: ******
$ aws ec2 describe-instances # runs as 'role/readonly'
...

similar projects

When I started working on this, I wasn't aware of quite how many other projects provide STS-based role switching. As far as I am aware, this project is the only one that both provides an aws-cli plugin and integrates with aws-cli's configuration and caching features. But if an aws-cli plugin isn't your style, try out one of the below options:

About

An aws-cli plugin that loads IAM Role credentials into environment variables

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages