AWS Okta Keyman - An AWS + Okta CLI for generating local AWS API keys
Clone or download

Apache PyPI version Python versions Downloads

CircleCI CC GPA CC Issues Coverage Status

AWS Okta Keyman

This is a simple command-line tool for logging into Okta and generating temporary Amazon AWS Credentials. This tool makes it easy and secure for your developers to generate short-lived, logged and user-attributed credentials that can be used for any of the Amazon SDK libraries or CLI tools.


We have support for logging into Okta, optionally handling MFA Authentication, and then generating new SAML authenticated AWS sessions. In paritcular, this tool has a few core features.

Optional MFA Authentication

If you organization requires MFA for the initial login into Okta, we will automatically detect that requirement during authentication and prompt the user to complete the Multi Factor Authentication.

In paritcular, there is support for standard passcode based auth, as well as support for Okta Verify with Push and Duo Auth. If both are available, Okta Verify with Push will be prioritized and a push notification is automatically sent to the user. If the user declines the validation, then optionally the Passcode can be entered in manually.

In the case of Duo Auth a web page is opened (served locally) for the user to interact with Duo and select their preferred authentication method. Once Duo is successful the user may close the browser or tab.

Supported MFA Solutions

  • Okta Verify
  • Duo Auth
  • Okta OTP
  • Google Auth OTP
  • Call OTP
  • Question/Answer

Windows Hello, U2F, email, and physical token (RSA, Symantec) are not supported at this time.

Multiple AWS Roles

AWS Okta Keyman supports multiple AWS roles when configued. The user is prompted to select the role they wish to use before the temporary keys are generated. An example of this is shown here:

17:10:21   (WARNING) Multiple AWS roles found; please select one
[0] Role: arn:aws:iam::012345678910:role/admin_noiam
[1] Role: arn:aws:iam::012345678910:role/readonly
[2] Role: arn:aws:iam::012345678910:role/admin_full
Select a role from above: 2
17:10:22   (INFO) Assuming role: arn:aws:iam::012345678910:role/admin_full

Re-Up Mode .. Automatic Credential Re-Generation

Amazon IAM only supports Federated Login sessions that last up to 1 hour. For developers, it can be painful to re-authenticate every hour during your work day. This is made much worse if your organization requires MFA on each login.

You may run the AWS Okta Keyman in "reup" mode to get around this. The tool will continue to run in a sleep loop periodically reaching out to Okta, generating a new SAML Assertion, and then generating updated Amazon AWS credentials. This can run for as long as your Okta administrator has allowed your Login Session to be - often a full work day.

See the --reup commandline option for help here!

Config file .. predefined settings for you or your org

The config file, which defaults to ~/.config/aws_okta_keyman.yml, allows you to pre-set things like your username, Okta organization name (subdomain), and AWS accounts and App IDs to make this script simpler to use. This also supports username assumption based on the current user when the username or email is configured as automatic-username if usernames only are an option or if you need full emails. Arguments will always be preferred to the config file so you can override what's in the config file as needed on each run of the tool.

Example config file:

org: example
  - name: Test
    appid: exampleAppIDFromOkta/123
  - name: Dev
    appid: exampleAppIDFromOkta/234
  - name: Prod
    appid: exampleAppIDFromOkta/345

When used you'll get a similar interface to AWS Role selection but for your AWS accounts:

$ aws_okta_keyman
16:56:47   (INFO) AWS Okta Keyman v0.3.0
16:56:47   (WARNING) No app ID provided; please select from available AWS accounts
[0] Account: Test
[1] Account: Dev
[2] Account: Prod
Select an account from above: 0
16:56:49   (INFO) Using account: Test / exampleAppIDFromOkta/123


Client Setup

Before you can install this tool you need to have a working Python installation with pip. If you're not sure if you have this a good place to start would be the Python Beginner's Guide .

Once your Python environment is configured simply run pip install aws-okta-keyman to install the tool.

Running AWS Okta Keyman

For detailed usage instructions, see the --help commandline argument.

Typical usage:

$ aws_okta_keyman -a <application id> -o <your org name> -u <your username>
08:27:44   (INFO) AWS Okta Keyman v0.2.0
08:27:48   (WARNING) Okta Verify Push being sent...
08:27:48   (INFO) Waiting for Okta Verification...
08:28:09   (INFO) Waiting for Okta Verification...
08:28:10   (INFO) Successfully authed Nathan V
08:28:10   (INFO) Getting SAML Assertion from foobar
08:28:11   (INFO) Found credentials in shared credentials file: ~/.aws/credentials
08:28:11   (INFO) Wrote profile "default" to /Users/nathan-v/.aws/credentials
08:28:11   (INFO) Session expires at 2017-07-24 16:28:13+00:00

Okta Setup

Before you can use this tool, your Okta administrator needs to set up Amazon/Okta integration using SAML roles.


This is a hard fork of nd_okta_auth by, Inc.. I decided to move ahead this way as I wanted to be able to move quickly and add features independently of the existing implementation. A big thank you to @diranged for the original work that this comes from.

The original code is heavily based on the previous work done by ThoughtWorksInc on their OktaAuth and AWS Role Credentials tools.

Developer Setup

If you are interested in working on the codebase, setting up your development environment is quick and easy.

$ virtualenv .venv
$ source .venv/bin/activate
$ pip install -r requirements.txt
$ pip install -r test_requirements.txt

Python Versions

Python 2.7.1+ and Python 3.5.0+ are supported

Running Tests

$ nosetests -vv --with-coverage --cover-erase --cover-package=aws_okta_keyman

Code Style

This project uses pycodestyle and pyflakes to check for style errors. Please use these tools to check changes before submitting PRs.


Copyright 2018 Nathan V

Copyright 2018, Inc

Licensed under the Apache License, Version 2.0. See LICENSE.txt file for details.

Some code in aws_okta_keyman/, aws_okta_keyman/, aws_okta_keyman/, and aws_okta_keyman/test/ is distributed under MIT license. See the source files for details. A copy of the license is in the LICENSE_MIT.txt file.