This repository provides a handful of Bash and Python scripts to make it easy to switch between multiple AWS profiles while handling credentials in a secure fashion.
It current supports acquiring credentials using a source profile whose credentials are stored in the operating system keychain, or via either AWS SSO or Okta.
- Python 3 - Required to execute the credential refresher
- AWS CLI version 2 - Used to support getting credentials via AWS SSO
- aws-vault - Store credentials in the local operating system keychain
- gimme-aws-creds - Fetches credentials using Okta
Instructions for each can be found at the corresponding links.
The scripts can be executed in place, but for convenience they can be copied to a location
in the system path (e.g. /usr/local/bin
). The aws-profile
script is a bit different; it
must be sourced since it needs to set an environment variable. The easiest way to do this
is to add the content of the aws-profile
file to ~/.bashrc
or ~/.bash_profile
.
To enable Bash completion on the scripts (highly recommended for ease of use), copy the
aws-profile-completion.bash
configuration to /usr/local/etc/bash_completion.d/
; note
this assumes that Bash completion is set up properly.
On Linux/MacOS systems, run ./install.sh
to execute the copy, and insert the aws-profile
function into the Bash profile. These steps can alternatively be executed manually.
Once the prerequisites have been installed, they need to be configured. The primary configuration
is stored in the AWS CLI config file at ~/.aws/config
or %HOMEPATH%\.aws\config
. Each profile
should be listed in this file, per typical CLI config.
Do not create a credentials
file, this will be done automatically by the credential refresher.
Each profile should at minimum specify a default region. The additional required parameters depend on the back-end method used to fetch credentials:
-
For profiles that use an IAM user with long-term credentials, there should not be any other options given (see the
user-profile
in the example below). To load the credentials into the operating system keychain, runaws-vault add <profile-name>
and follow the prompts. -
For profiles that assume a role via a source profile, store the source profile credentials using
aws-vault
as described above, then add thesource_profile
value to reference them, and therole_arn
to be assumed. Note that the role must have a trust policy that allows the user in the source profile to assume it. See therole-profile
example below. -
For profiles that use AWS SSO, configure the profile per the instructions, i.e. with the
sso_start_url
,sso_region
,sso_account_id
, andsso_role_name
fields. See also thesso-profile
example below. -
For Okta profiles, add
okta_profile
,okta_account_id
, andokta_role_name
fields as shown in theokta-profile
example. These values should match what's configured in thegimme-aws-creds
config file stored at~/.okta_aws_login_config
.
An example profile configuration is below:
[default]
output=json
[profile user-profile]
region = us-west-2
[profile role-profile]
source_profile = user-profile
role_arn = arn:aws:iam::123456789100:role/example
[profile sso-profile]
sso_start_url = https://example-domain.awsapps.com/start
sso_region = us-west-2
sso_account_id = 123456789100
sso_role_name = ExampleRole
[profile okta-profile]
okta_profile = example
okta_account_id = 123456789100
okta_role_name = ExampleRole
A ~/.okta_aws_login_config
file must be set up if any Okta-backed profiles are configured
(this step can be skipped if not). Run gimme-aws-creds --action-configure
and follow the
prompts. An example file is below. Precise configuration will vary, but a few key items:
- Each Okta profile name (the part in brackets) must match the
okta_profile
value in the AWS CLI config - The
cred_profile
value should match the corresponding profile name in the AWS CLI config - The
write_aws_creds
field should be false (the credential refresher will take care of saving them) - The
output_format
must bejson
so the credential refresher can parse the output
[example]
okta_username = user@example.com
okta_org_url = https://example-domain.okta.com
app_url = https://example-domain.okta.com/home/amazon_aws/0123456789abcdefABCD/123
gimme_creds_server = appurl
preferred_mfa_type = push
remember_device = True
device_token = 1234567890abcABC-defgABCD
resolve_aws_alias = False
write_aws_creds = False
cred_profile = okta-profile
output_format = json
There are two commands provided:
-
aws-profile [PROFILE_NAME]
- If run without a parameter, this function parses all profile names from the config file and lists them, highlighting the active one (i.e. the value of theAWS_PROFILE
variable). If run with a profile name as a parameter, it sets theAWS_PROFILE
variable to that name, which is the common way that the AWS CLI and other tools read a default profile. This prevents needing a--profile
switch on every CLI command. Note that if the completion config was installedaws-profile
can do tab-completion when entering a profile name parameter. -
aws-refresh-credentials [PROFILE_NAME] [PROFILE_NAME] ...
- Automatically fetches temporary credentials for the given profiles and populates the credentials file (i.e.~/.aws/credentials
) with the values, so they're available for the AWS CLI and any other tools that shared their config (e.g. boto3). Note that in addition to the provided profile names on the command line, the profile set inAWS_PROFILE
will also be fetched; thus when working in a terminal window with a valid profile set withaws-profile
, this script can be run without any parameters to quickly get that profile a set of credentials. If noAWS_PROFILE
is set, and the script is run without any parameters, it will refresh credentials for all profiles in the config.
Note that if required, there may prompts for additional information during the credential refresh (e.g. keychain password for locally-stored credentials, password and MFA prompts for the SSO profiles). These can happen either in the terminal, or they may open a browser tab, depending on the particular back-end implementation. The script will wait for entry before proceeding.
Pull requests are welcomed, especially ones that add support for new credential fetching methods.
Please lint all changes with flake8 --max-line-length=120
before submitting. Also review
the Contributing Guidelines and the Code of Conduct.
- Jud Neer (judneer@amazon.com)
This project is licensed under the MIT-0 License. See the LICENSE file for details.