aws-runas A friendly way to assume roles in AWS View on Github View on Github

Quick Start Guide

This document will walk you through the basic installation and configuration of the tool to hopefully get you up and running quickly

Installation

Download the latest release, using the zip file appropriate for the system you are running the tool on. Supported platforms are:

For Linux, DEB and RPM packages are also available for each supported architecture.

If you do not see a download for your system, create a new issue here, and we’ll work on getting the appropriate build created for you.

MacOS and Linux

If you are using the DEB or RPM package for Linux, no additional work is required other than installing the package.

If using the ZIP file, unzip it and move the extracted aws-runas file to a location in your PATH, so you can execute the command without having to provide the full path to the file. Many people will simply create a bin directory inside their home directory (mkdir ~/bin), and add that to their shell’s PATH, so they have a locally-controlled directory containing their individual tooling.

Shell completion

Tab completion for bash and zsh is supported in aws-runas. Using the DEB and RPM packages automatically installs the completion logic in a system-wide location. When using the zip file to install aws-runas, you will need to manually configure the command completion.

Bash auto-complete

To configure auto-completion at a system-wide level, install the file from the git repository as a file named /etc/bash_completion.d/aws-runas on the local system. If you only want to install the auto-completion for some users, download that same file, and in the user’s .bashrc add the following lines:

PROG=aws-runas
source /path/to/aws-runas-bash-completion
Zsh auto-complete

To configure auto-completion when using zsh, download the file from the git repository, and in the user’s .zshrc add the following lines:

PROG=aws-runas
_CLI_ZSH_AUTOCOMPLETE_HACK=1
source /path/to/aws-runas-zsh-completion

Windows

After downloading the ZIP file, unzip it and move the extracted aws-runas.exe file to a location where it is easily accessible, like on the desktop, or in your home directory.

Configuration

Both the AWS credentials and configuration files live in a directory named .aws in your user’s home directory. On Windows, this is %USERPROFILE%\.aws and on MacOS and Linux, this would be $HOME/.aws. Create this directory if it does not already exist.

IAM

When using an AWS IAM user to assume a role, the sections below are the minimal setup required to configure a profile for a role in the configuration file. The first thing you’ll want to do is configure your IAM user credentials in the appropriate file so the tools can call the necessary AWS APIs.

Credentials File

Using the text editor of your choice, create a file named credentials in the .aws folder in your home directory. In this file, paste the following bit of text:

[default]
aws_access_key_id     = MY_AWS_ACCESS_KEY_GOES_HERE
aws_secret_access_key = MY_AWS_SECRET_KEY_GOES_HERE

The values for the items on the right side of the ‘=’ sign can be obtained by logging in to the AWS console, navigating to your user account in the IAM service console, selecting the ‘Security credentials’ tab, and clicking on the ‘Create access key’ button. Copy and paste the provided values at the appropriate place in the file, save the data, and exit.

On MacOS and Linux systems, it would be advisable to chmod this file to only be accessible to your user, since these keys are secure credentials used to access the AWS API. Running chmod 600 ~/.aws/credentials should do the trick.

Configuration File

Using the text editor of your choice, create a file named config in the .aws folder in your home directory. In this file, paste the following bit of text, save the file, and exit:

[default]
region = us-east-1

The above data is enough to allow you to use aws-runas to list some of the IAM roles you have access to (the ‘-l’ option), to find your MFA device ARN (if required, using the ‘-m’ option), or create a set of session token credentials (the ‘-s’ option). However, it isn’t enough to make aws-runas assume a role and provide you access to AWS resources outside of the account where your IAM user is managed.

To configure a role for aws-runas to assume, re-open the config file in your text editor, and create a profile. It should look something like this:

[profile my-profile]
source_profile = default
role_arn       = arn:aws:iam::012345678901:role/my-role
mfa_serial     = arn:aws:iam::9876543221098:mfa/my_iam_user

This will create a profile called “my-profile”, which is configured to assume a role called “my-role”. The “source_profile” line is critical, as it tells tools making AWS API calls (like aws-runas) to use the credentials in the credentials file under that section name. The value for role_arn can be found by running aws-runas -l and selecting a value from that. The “mfa_serial” line is optional, you should know whether you need to have that configured (your IAM administrators should be able to give you the answer). If you do not need to have MFA, then you can delete this line. Otherwise, you should configure this value with the data returned from running aws-runas -m (after configuring the MFA device for your IAM user, of course!)

Create a profile section for each role you want to assume in AWS, and you should be well on your way!

SAML

If enabled for your AWS account(s), you can configure aws-runas to leverage SAML single sign-on and authenticate against your organizations identity provider and perform the necessary handshaking with AWS to perform the Assume Role With SAML operation based on the authorizations granted by your identity provider. To configure a profile for SAML, you will only need to define the profile parameters in the config file in the .aws folder in your home directory. You can optionally set your identity provider password in the credentials file as well.

Each SAML identity provider has their own process for handling authentication of a user and integrating with multi-factor authentication. This means that aws-runas can’t magically support every SAML provider. If you find a case where your identity provider is not yet supported by the tool, open a Github issue, and we’ll look at adding support for it.

To set up a simple SAML-integrated profile, you should be able to copy and paste the snippet below while editing the config file:

[profile my-profile]
saml_auth_url = https://example.org/saml/auth
saml_username = my-user-name
role_arn      = arn:aws:iam::1234567890:role/MyRole

You’ll need to modify all the values to the right of the = with the values specific to your organization. The saml_auth_url parameter is the URL of the authentication endpoint for yor specific identity provider. The role_arn parameter is the AWS ARN of the IAM role you will assume after the SAML authentication is complete. You should be able to get the necessary values for both of these parameters from the person or team responsible for managing your AWS accounts. The saml_username parameter is optional, but is a handy shortcut to supply your username to the SAML provider, instead of getting prompted for it each time you need to authenticate to your SAML identity provider.

If you do not configure a password for your identity provider, you will be prompted to enter it when aws-runas is required to authenticate with the identity provider. To skip this prompting, you can configure aws-runas to store your password in an obfuscated form using the aws-runas password my-profile command. You will be prompted to enter your password for the identity provider, and the value will be stored in the .aws/credentials file. If this password changes, you will need to re-run this step and provide the new password, otherwise aws-runas will fail, and you potentially risk locking your account in your organization’s identity provider.

Web Identity

If enabled for your AWS account(s), you can configure aws-runas to leverage OIDC single sign-on and authenticate against your organizations identity provider and perform the necessary handshaking with AWS to perform the Assume Role With Web Identity operation based on the authorizations granted by your identity provider. To configure a profile for Web Identity (OIDC), you will only need to define the profile parameters in the config file in the .aws folder in your home directory. You can optionally set your identity provider password in the credentials file as well.

Each OIDC identity provider has their own process for handling authentication of a user and integrating with multi-factor authentication. This means that aws-runas can’t magically support every provider. If you find a case where your identity provider is not yet supported by the tool, open a Github issue, and we’ll look at adding support for it.

To set up a simple Web Identity-integrated profile, you should be able to copy and paste the snippet below while editing the config file:

[profile my-profile]
web_identity_auth_url     = https://example.org/oauth2
web_identity_username     = my-user-name
web_identity_client_id    = theClientID
web_identity_redirect_uri = app:/callback
role_arn                  = arn:aws:iam::1234567890:role/MyRole

You’ll need to modify all the values to the right of the = with the values specific to your organization. The web_identity_auth_url parameter is the URL of the authentication endpoint for yor specific identity provider. The web_identity_client_id and web_identity_redirect_uri parameters are OIDC-specific configuration for your identity provider. The role_arn parameter is the AWS ARN of the IAM role you will assume after the OIDC authentication is complete. You should be able to get the necessary values for all of these parameters from the person or team responsible for managing your AWS accounts. The web_identity_username parameter is optional, but is a handy shortcut to supply your username to the OIDC provider, instead of getting prompted for it each time you need to authenticate to your OIDC identity provider.

If you do not configure a password for your identity provider, you will be prompted to enter it when aws-runas is required to authenticate with the identity provider. To skip this prompting, you can configure aws-runas to store your password in an obfuscated form using the aws-runas password my-profile command. You will be prompted to enter your password for the identity provider, and the value will be stored in the .aws/credentials file. If this password changes, you will need to re-run this step and provide the new password, otherwise aws-runas will fail, and you potentially risk locking your account in your organization’s identity provider.

Running

At this point, we should have enough configuration to execute aws-runas with some level of success. The aws-runas tool is designed to be a command-line driven utility, so you’ll need to fire up your command prompt or terminal emulator to use the tool. Using the example configuration above, you should be able to execute the command like:

> aws-runas my-profile

if you are required to use MFA, you will be prompted to enter your MFA code. Then you should see output similar to:

export AWS_REGION='us-east-1'
export AWS_DEFAULT_REGION='us-east-1'
export AWS_ACCESS_KEY_ID='ASIAROLEACCESSKEY'
export AWS_SECRET_ACCESS_KEY='RoleSecretKey'
export AWS_SESSION_TOKEN='RoleSessionToken'

The AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN values will be some nonsensical string, particular to the set of credentials AWS generated for you. On Windows, the leading “export” will say “set” instead to allow the returned values to be set as environment variables in your command line session. This is a simple test to validate that the configuration is correct.

If you have the awscli command line tools installed, you can use aws-runas to call the awscli tools. The following example shows how to use aws-runas to list the S3 buckets in the account for the role (assuming your role grants you the permissions to list S3 buckets).
aws-runas my-profile aws s3 ls