.. image:: https://github.com/godaddy/aws-okta-processor/workflows/.github/workflows/build.yml/badge.svg?branch=master :target: https://github.com/godaddy/aws-okta-processor/actions?query=workflow%3A.github%2Fworkflows%2Fbuild.yml :alt: Build Status
.. image:: https://codecov.io/gh/godaddy/aws-okta-processor/branch/master/graph/badge.svg :target: https://codecov.io/gh/godaddy/aws-okta-processor :alt: Coverage
.. image:: https://img.shields.io/pypi/v/aws-okta-processor.svg :target: https://pypi.python.org/pypi/aws-okta-processor :alt: Latest Version
.. image:: https://img.shields.io/pypi/status/aws-okta-processor :target: https://pypi.python.org/pypi/aws-okta-processor :alt: Status
.. image:: https://img.shields.io/pypi/pyversions/aws-okta-processor :target: https://pypi.python.org/pypi/aws-okta-processor :alt: Python Version
.. image:: https://img.shields.io/pypi/dm/aws-okta-processor :target: https://pypi.python.org/pypi/aws-okta-processor :alt: Downloads
This package provides a command for fetching AWS credentials through Okta.
The recommended way to install aws-okta-processor is using pipx_. This has the
benefit that the command is available in your shell without needing to activate
a virtualenv while still keeping its dependencies isolated from site-packages::
$ pipx install aws-okta-processor
and, to upgrade to a new version::
$ pipx upgrade aws-okta-processor
You can also install with pip_ in a virtualenv::
$ pip install aws-okta-processor
or, if you are not installing in a virtualenv, to install globally::
$ sudo pip install aws-okta-processor
or for your user::
$ pip install --user aws-okta-processor
If you have aws-okta-processor installed with pip_ and want to upgrade to the latest
version you can run::
$ pip install --upgrade aws-okta-processor
.. note::
On OS X, if you see an error regarding the version of six that came with
distutils in El Capitan, use the ``--ignore-installed`` option::
$ sudo pip install aws-okta-processor --ignore-installed six
This will install the aws-okta-processor package as well as all dependencies. You can
also just download the tarball_. Once you have the
aws-okta-processor directory structure on your workstation, you can just run::
$ cd <path_to_aws-okta-processor>
$ python setup.py install
This package is best used in AWS Named Profiles_
with tools and libraries that recognize credential_process_.
To setup aws-okta-processor in a profile create an INI formatted file like this::
[default]
credential_process=aws-okta-processor authenticate --user <user_name> --organization <organization>.okta.com
and place it in ~/.aws/credentials (or in
%UserProfile%\.aws/credentials on Windows). Then run::
$ pip install awscli
$ aws sts get-caller-identity
Supply a password then select your AWS Okta application and account role if prompted. The AWS CLI command will return a result showing the assumed account role. If you run the AWS CLI command again you will get the same role back without any prompts due to caching.
For tools and libraries that do not recognize credential_process aws-okta-processor
can be ran to export the following as environment variables::
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKEN
For Linux or OSX run::
$ eval $(aws-okta-processor authenticate --environment --user <user_name> --organization <organization>.okta.com)
On Unix systems pass a --target-shell in order to change the
export command output. Bash is the default target shell.
We also allow fish shell as a valid target::
$ eval (aws-okta-processor authenticate --environment --user <user_name> --organization <organization>.okta.com --target-shell fish)
For Windows run::
$ Invoke-Expression (aws-okta-processor authenticate --environment --user <user_name> --organization <organization>.okta.com)
Additional variables can also be passed to aws-okta-processors authenticate command
as options or environment variables as outlined in the table below.
============== ================ ======================= ======================================== Variable Option Environment Variable Description ============== ================ ======================= ======================================== user --user AWS_OKTA_USER Okta user name
password --pass AWS_OKTA_PASS Okta user password
organization --organization AWS_OKTA_ORGANIZATION Okta FQDN for Organization
application --application AWS_OKTA_APPLICATION Okta AWS application URL
role --role AWS_OKTA_ROLE AWS Role ARN
secondary_role --secondary-role AWS_OKTA_SECONDARY_ROLE Secondary AWS Role ARN
account_alias --account-alias AWS_OKTA_ACCOUNT_ALIAS AWS Account Filter
region --region AWS_OKTA_REGION AWS Region
duration --duration AWS_OKTA_DURATION Duration in seconds for AWS session
key --key AWS_OKTA_KEY Key used in generating AWS session cache
environment --environment Output command to set ENV variables
silent --silent Silence Info output
factor --factor AWS_OKTA_FACTOR MFA type. push:okta, token:software:totp:okta, token:software:totp:google and token:hardware:yubico are supported.
no_okta_cache --no-okta-cache AWS_OKTA_NO_OKTA_CACHE Do not read okta cache
no_aws_cache --no-aws-cache AWS_OKTA_NO_AWS_CACHE Do not read aws cache
target_shell --target-shell AWS_OKTA_TARGET_SHELL Target shell to format export command
sign_in_url --sign-in-url AWS_OKTA_SIGN_IN_URL AWS Sign In URL ============== ================ ======================= ========================================
^^^^^^^^ Examples ^^^^^^^^
If you do not want aws-okta-processor to prompt for any selection input you can export the following::
$ export AWS_OKTA_APPLICATION=<application_url> AWS_OKTA_ROLE=<role_arn> AWS_OKTA_FACTOR=<factor_type>
Or pass additional options to the command::
$ aws-okta-processor authenticate --user <user_name> --organization <organization>.okta.com --application <application_url> --role <role_arn> --factor <factor_type>
This package leverages caching of both the Okta session and AWS sessions. It's helpful to understand how this caching works to avoid confusion when attempting to switch between AWS roles.
^^^^ Okta ^^^^
When aws-okta-processor attempts authentication it will check ~/.aws-okta-processor/cache/
for a file named <user>-<organization>-session.json based on the user and organization
option values passed. If the file is not found or the session contents are stale then
aws-okta-processor will create a new session and write it to ~/.aws-okta-processor/cache/.
If the file exists and the session is not stale then the existing session gets refreshed.
^^^ AWS ^^^
After aws-okta-processor has a session with Okta and an AWS role has been selected it will fetch
the role's keys and session token. This session information from the AWS role gets cached as a
json file under ~/.aws/boto/cache. The file name is a SHA1 hash based on a combination the
user, organization and key option values passed to the command.
If you want to store a seperate AWS role session cache for each role assumed using the same
user and organization option values then pass a unique value to key.
Named profiles for different roles can then be defined in ~/.aws/credentials with content like this::
[role_one]
credential_process=aws-okta-processor authenticate --user <user_name> --organization <organization>.okta.com --application <application_url> --role <role_one_arn> --factor <factor_type> --key role_one
[role_two]
credential_process=aws-okta-processor authenticate --user <user_name> --organization <organization>.okta.com --application <application_url> --role <role_two_arn> --factor <factor_type> --key role_two
To clear all AWS session caches run::
$ rm ~/.aws/boto/cache/*
If you can only assume a role from another role, you can assume both roles using --role and --secondary-role. Use
--role to specify the first role ARN, then --secondary-role to specify the role ARN assumed from --role.
Example::
aws-okta-processor authenticate --user jdoe ... --role arn:aws:iam::111111111:role/OpsUser --secondary-role arn:aws:iam::111111111:role/SecretsAdmin
aws-okta-processor can inherit arguments from a .awsoktaprocessor file located in the user's home directory or the current working
directory.
.awsoktaprocessor
.. code-block:: ini
[defaults]
user=jdoe
[authenticate]
user=ssmith
In this example...
authenticate > user overrides defaults > user{workingDir}/.awsoktaprocessor overrides ~/.awsoktaprocessoraws-okta-processor arguments override any options from dotfilesTo get roles, use the get-roles command. This command supports outputing the roles as AWS profiles, JSON, or custom formatted text.
.. code-block:: bash
aws-okta-processor get-roles -u jdoe -o mycompany.okta.com --output=profiles > ~/.aws/credentials
aws-okta-processor get-roles -u jdoe -o mycompany.okta.com --output=text --output-format="{account},{role}"
aws-okta-processor get-roles -u jdoe -o mycompany.okta.com --output=json
Output Types
json (default): output as JSONprofiles: output AWS profiles to be stored in ~/.aws/credentialstext: custom formatted text using --output-format and tokensOutput Format Tokens
{account}: name of the account{account_id}: account Id{account_raw}: account information as seen on Okta site (Account: blah-blah (id)){application_url}: full Okta application url{organization}: organization as provided{role}: role ARN{role_suffix}: last element of the role (delimited using AWS_OKTA_ROLE_SUFFIX_DELIMITER or -){user}: user as providedopen an issue <https://github.com/godaddy/aws-okta-processor/issues/new>__This package was influenced by AlainODea <https://github.com/AlainODea>'s
work on okta-aws-cli-assume-role <https://github.com/oktadeveloper/okta-aws-cli-assume-role>.
.. _pip: http://www.pip-installer.org/en/latest/
.. _pipx: https://pipxproject.github.io/pipx/
.. _download the tarball: https://pypi.org/project/aws-okta-processor/
.. _AWS Named Profiles: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html
.. _credential_process: https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#sourcing-credentials-from-external-processes
FAQs
Resource for fetching AWS Role credentials from Okta
We found that aws-okta-processor demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.
Security News
Research
Socket researchers found a malicious Maven package impersonating the legitimate ‘XZ for Java’ library, introducing a backdoor for remote code execution.