This tool is for accessing the AWS API for AWS accounts you normally log into via okta. Normally, when you log in to an account via okta, you are assigned an IAM role, and don't have an actual user within AWS. This means you don't have any API keys you can use to access the AWS API via the command line.
This tool will prompt you for your Okta credentials, and generate temporary API keys you can use to access the AWS API with.
Okta_aws requires Python 3 to run.
If you have Homebrew, you can use it to install okta_aws
:
brew tap chef/okta_aws
brew install okta_aws
To do the same thing in one step, you can run:
brew install chef/okta_aws/okta_aws
Due to a bug in the
version of the AWS CLI found in Ubuntu packages, you will need to use
the AWS CLI installed via pip
instead (okta_aws
currently
interacts with the AWS API via the CLI).
Once you have installed the newer AWS CLI, you can install okta_aws
using pip
:
sudo apt-get remove awscli
sudo apt-get install python3 python3-pip
sudo python3 -m pip install --upgrade awscli
sudo python3 -m pip install --upgrade okta_aws
Alternatively, you can install via pip
:
pip install okta_aws
To install from source, clone this repository and run:
python setup.py install
Make a file in your home directory called .okta_aws.toml
:
[general]
username="yourusername"
okta_server="yourcompany.okta.com"
The values are as follows:
username
: your okta username.okta_server
: the okta domain your company uses. It is usually something likeyourcompanyname.okta.com
.
There are some optional settings too:
short_profile_names
- okta_aws will fetch a list of AWS accounts you have been assigned directly from okta, and will use the name in okta as the profile name referred to by the AWS tools. However, the name of the application in okta is often verbose. With this option turned on (it defaults to true), the profile names will be shortened into something easier to type. For example 'MyCompany Engineering (all devs) AWS' will becomemycompany-engineering
. The exact rules are:- Any trailing 'AWS' suffix, if present, is removed
- Anything in parentheses is stripped
- Everything is converted to lowercaase
- Spaces are stripped and replaced with dashes
cookie_file
- the location where the okta session cookie is stored. This defaults to~/.okta_aws_cookie
.session_duration
- How long to request that the AWS temporary credentials should be valid for. This defaults to3600
(1 hour), but you can choose a shorter or longer value up to43200
(12 hours).- Note: in order to choose a session length longer than 1 hour, you need to
configure the role in AWS to allow longer sessions. In the IAM console,
find the role and exit the
Maximum CLI/API session duration
setting.
- Note: in order to choose a session length longer than 1 hour, you need to
configure the role in AWS to allow longer sessions. In the IAM console,
find the role and exit the
role_arn
- the ARN or name of the role to assume. This only needs to be set if you have more than one role and are prompted to select which role to assume when you run okta_aws.
Each of these settings can be set per-profile. To do this, create a new
section in the configuration file with the name of the profile, and put your
per-profile settings here. For example, in order to use a longer session
length for the mycompany-dev
profile, add this to your ~/.okta_aws.toml
file:
[mycompany-dev]
session_duration = 43200
Or, if you are prompted when logging into the mycompany-staging
profile
which role you want to use, then you can configure a default role as follows:
[mycompany-staging]
role_arn = "Okta_PowerUser"
# Alternatively you can specify the full ARN
# role_arn = "arn:aws:iam::1234567890:role/Okta_PowerUser"
Sometimes, the profile name obtained from okta doesn't match the profile name
you want to use in your AWS credentials file (for example, you might have a
specific profile name hardcoded in scripts). In these cases, you can configure
a profile name to be an alias of another. To do this, add an [aliases]
section to your .okta_aws.toml
file. For example, if okta_aws --list
shows
an available profile of companyname-engineering
but you have
engineering
configured as a profile name in your scripts, you can do:
[aliases]
engineering = "companyname-engineering"
Then, you just set AWS_PROFILE
to engineering
, or pass engineering
as an
argument to okta_aws, and it will log in with the companyname-engineering
profile, while storing the credentials in an engineering
profile in your
~/.aws/credentials
file.
If you want to configure profile specific settings for a profile that has an alias, you can configure them under either the profile name itself, or the alias. If you configure the settings under the 'real' name of the profile, then those settings will also be used if you refer to the profile by its alias. If you configure them under the alias, then they will only take effect if you refer to the profile by its alias.
If the profile name includes 'govcloud', then okta_aws will use the appropriate region for fetching govcloud credentials (us-gov-east-1).
Run okta_aws PROFILENAME
, or run okta_aws
without any arguments and
okta_aws will use the AWS_PROFILE
environment variable if you have it set.
To fetch credentials for all profiles you have access to, run okta_aws --all
.
To list the available profiles, run okta_aws --list
.
The first time you run okta_aws
, you will be prompted for your okta username
and password. On subsequent runs, if you are still logged into okta and your
session hasn't expired, then you won't have to log in again.
Once you have entered your okta username and password, a temporary token will be obtained for you and stored in your AWS credentials file. You can then use the aws api as normal, passing in the profile name you gave to okta_aws.
If you have been assigned multiple possible roles when the aws account was set
up for you in okta, then you will be prompted which one of them you want to
use (e.g. Okta_PowerUser or Okta_AdminAccess). Select which one you want from
the menu if prompted. You can also configure a default role to assume in
~/.okta_aws.toml
.
The AWS token you receive will only last for an hour. To get a new token, re-run okta_aws.
You can run okta_aws a second time to retrieve a new token before the old one expires. If you wish, you can run one of the following to automatically refresh the token once every 55 minutes (allowing some grace period before the token expires):
while true; do okta_aws PROFILENAME; sleep 3300; done
while true; do okta_aws --all; sleep 3300; done
okta_aws will run without prompting for anything one you have logged in and,
if necessary, configured a default profile in ~/.okta_aws.toml
.
Users of zsh may find this oh-my-zsh
plugin useful for shell-integrated
auto-refresh: okta-aws plugin for zsh
If you're having issues running okta_aws, there's a few things to check:
okta_aws --version
- should match most recent
python --version
- should be 3.X
We also recently saw someone where the error looked like this, user had environment variables set that put python 3.6 directories first in the PATH, when python 3.7 was installed. Removing those lines from .bash_profile
fixed the issue:
-bash: /Library/Frameworks/Python.framework/Versions/3.6/bin/okta_aws: /usr/local/Cellar/okta_aws/0.5.3/libexec/bin/python3.7: bad interpreter: No such file or directory
- okta-aws-cli-assume-role - Okta's own tool
- oktaauth - Python library for working with okta
- segmentio/aws-okta - uses assumerole to connect to multiple aws accounts while signing into a primary aws account in okta.
- aws-vault - tool for securely storing aws credentials
- okta_aws_login
- okta-awscli