Package: aws-okta-processor
This package provides a command for fetching AWS credentials through Okta.InstallationThe recommended way to install aws-okta-processor is usingpipx. 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-processorand, to upgrade to a new version:$ pipx upgrade aws-okta-processorYou can also install withpipin avirtualenv:$ pip install aws-okta-processoror, if you are not installing in avirtualenv, to install globally:$ sudo pip install aws-okta-processoror for your user:$ pip install --user aws-okta-processorIf you have aws-okta-processor installed withpipand want to upgrade to the latest
version you can run:$ pip install --upgrade aws-okta-processorNoteOn OS X, if you see an error regarding the version of six that came with
distutils in El Capitan, use the--ignore-installedoption:$ sudo pip install aws-okta-processor --ignore-installed sixThis will install the aws-okta-processor package as well as all dependencies.  You can
also justdownload 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 installGetting StartedThis package is best used inAWS Named Profileswith tools and libraries that recognizecredential_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.comand place it in~/.aws/credentials(or in%UserProfile%\.aws/credentialson Windows). Then run:$ pip install awscli
$ aws sts get-caller-identitySupply 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 recognizecredential_processaws-okta-processor
can be ran to export the following as environment variables:AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_SESSION_TOKENFor Linux or OSX run:$ eval $(aws-okta-processor authenticate --environment --user <user_name> --organization <organization>.okta.com)On Unix systems pass a–target-shellin order to change the
export command output. Bash is the default target shell.
We also allow [fish shell](https://fishshell.com/) 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)Other Configurable VariablesAdditional variables can also be passed to aws-okta-processorsauthenticatecommand
as options or environment variables as outlined in the table below.VariableOptionEnvironment VariableDescriptionuser–userAWS_OKTA_USEROkta user namepassword–passAWS_OKTA_PASSOkta user passwordorganization–organizationAWS_OKTA_ORGANIZATIONOkta FQDN for Organizationapplication–applicationAWS_OKTA_APPLICATIONOkta AWS application URLrole–roleAWS_OKTA_ROLEAWS Role ARNsecondary_role–secondary-roleAWS_OKTA_SECONDARY_ROLESecondary AWS Role ARNaccount_alias–account-aliasAWS_OKTA_ACCOUNT_ALIASAWS Account Filterregion–regionAWS_OKTA_REGIONAWS Regionduration–durationAWS_OKTA_DURATIONDuration in seconds for AWS sessionkey–keyAWS_OKTA_KEYKey used in generating AWS session cacheenvironment–environmentOutput command to set ENV variablessilent–silentSilence Info outputfactor–factorAWS_OKTA_FACTORMFA type.push:okta,token:software:totp:okta,token:software:totp:googleandtoken:hardware:yubicoare supported.no_okta_cache–no-okta-cacheAWS_OKTA_NO_OKTA_CACHEDo not read okta cacheno_aws_cache–no-aws-cacheAWS_OKTA_NO_AWS_CACHEDo not read aws cachetarget_shell–target-shellAWS_OKTA_TARGET_SHELLTarget shell to format export commandsign_in_url–sign-in-urlAWS_OKTA_SIGN_IN_URLAWS Sign In URLExamplesIf 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>CachingThis 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.OktaWhen aws-okta-processor attempts authentication it will check~/.aws-okta-processor/cache/for a file named<user>-<organization>-session.jsonbased on theuserandorganizationoption 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.AWSAfter 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 theuser,organizationandkeyoption values passed to the command.If you want to store a seperate AWS role session cache for each role assumed using the sameuserandorganizationoption values then pass a unique value tokey.
Named profiles for different roles can then be defined in~/.aws/credentialswith 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_twoTo clear all AWS session caches run:$ rm ~/.aws/boto/cache/*$ rm ~/.aws/boto/cache/*Assuming a Secondary RoleIf you can only assume a role from another role, you can assume both roles using--roleand--secondary-role. Use--roleto specify the first role ARN, then--secondary-roleto 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/SecretsAdminProject or User Configurationaws-okta-processorcan inherit arguments from a.awsoktaprocessorfile located in the user’s home directory or the current working
directory..awsoktaprocessor[defaults]user=jdoe[authenticate]user=ssmithIn this example…authenticate > useroverridesdefaults > user{workingDir}/.awsoktaprocessoroverrides~/.awsoktaprocessoraws-okta-processorarguments override any options from dotfilesGet RolesTo get roles, use theget-rolescommand. This command supports outputing the roles as AWS profiles, JSON, or custom formatted text.# write all the roles as AWS profilesaws-okta-processorget-roles-ujdoe-omycompany.okta.com--output=profiles>~/.aws/credentials# get account and roleaws-okta-processorget-roles-ujdoe-omycompany.okta.com--output=text--output-format="{account},{role}"# get JSONaws-okta-processorget-roles-ujdoe-omycompany.okta.com--output=jsonOutput Typesjson(default): output as JSONprofiles: output AWS profiles to be stored in~/.aws/credentialstext: custom formatted text using--output-formatand 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 usingAWS_OKTA_ROLE_SUFFIX_DELIMITERor-){user}: user as providedGetting HelpIf it turns out that you may have found a bug, pleaseopen an issueAcknowledgmentsThis package was influenced byAlainODea’s
work onokta-aws-cli-assume-role.