okta-aws-cli-assume-role
Okta AWS CLI Assume Role tool
ℹ️ Disclaimer: This tool is community-supported and is maintained by members of the Okta team for developers and IT professionals. This tool is not an official Okta product and does not qualify for any Okta support. Anyone who chooses to use this tool must ensure that their implementation meets any applicable legal obligations including any Okta terms and conditions.
New to Amazon Web Services with Okta? Start with the Configuring AWS in Okta.
This tool has been verified to work on macOS Sierra, High Sierra, Windows Server 2012 R2, Windows 10, and Ubuntu 16.04 LTS, and is expected to work on other Linux systems as well.
- Installation
- Usage
- Compiling the application
- Configuring AWS in Okta
- Configuring the application
- History
- Troubleshooting
- Getting help
- License
Installation
Windows
-
Run the following in a PowerShell console
Set-ExecutionPolicy -Scope Process -ExecutionPolicy unrestricted -Force; Invoke-Expression ((New-Object Net.WebClient).DownloadString('https://raw.githubusercontent.com/oktadev/okta-aws-cli-assume-role/master/bin/Install-OktaAwsCli.ps1')); .$profile
-
Customize %userprofile%.oktaconfig.properties and set OKTA_ORG and OKTA_AWS_APP_URL appropriately. For example,
OKTA_ORG=acmecorp.oktapreview.com OKTA_AWS_APP_URL=https://acmecorp.oktapreview.com/home/amazon_aws/0oa5zrwfs815KJmVF0h7/137
macOS/Linux
-
Run the following in a Terminal, optionally setting a custom
PREFIX
value (default:~/.okta
):PREFIX=~/.okta bash <(curl -fsSL https://raw.githubusercontent.com/oktadev/okta-aws-cli-assume-role/master/bin/install.sh) -i
-
Customize
~/.okta/config.properties
and set OKTA_ORG and OKTA_AWS_APP_URL appropriately. For example,OKTA_ORG=acmecorp.oktapreview.com OKTA_AWS_APP_URL=https://acmecorp.oktapreview.com/home/amazon_aws/0oa5zrwfs815KJmVF0h7/137
-
Make sure
/usr/local/bin
(or whatever$PREFIX/bin
is) is in your PATH
Docker
-
Create
~/.okta/config.properties
and set OKTA_ORG and OKTA_AWS_APP_URL appropriately. For example,OKTA_ORG=acmecorp.oktapreview.com OKTA_AWS_APP_URL=https://acmecorp.oktapreview.com/home/amazon_aws/0oa5zrwfs815KJmVF0h7/137
-
Run this command:
docker run -v ~/.okta/config.properties:/root/.okta/config.properties -it tomsmithokta/okta-awscli-java
Read more at @tom-smith-okta’s okta-awscli-java Docker repo.
Manual install
Create a .okta
directory in your home directory. For example, ~/.okta
.
Download the latest release JAR and put it in .okta
:
https://github.com/oktadev/okta-aws-cli-assume-role/releases
Create ~/.okta/config.properties
and set
OKTA_ORG and OKTA_AWS_APP_URL appropriately. For example,
OKTA_ORG=acmecorp.oktapreview.com OKTA_AWS_APP_URL=https://acmecorp.oktapreview.com/home/amazon_aws/0oa5zrwfs815KJmVF0h7/137
Create ~/.okta/logging.properties
with the following content,
com.amazonaws.auth.profile.internal.BasicProfileConfigLoader = NONE
Copy scripts from .okta/bin
to somewhere on your PATH.
Usage
Verify your setup with a simple command:
okta-aws test sts get-caller-identity
This will prompt for Okta credentials, log you into AWS, let you pick a role, and store a session profile called test for you.
Run the program again to see session resumption (you won’t be asked for Okta credentials until the session expires):
okta-aws test sts get-caller-identity
NOTE: okta-aws is a function loaded from your shell profile, not a typical program or command stored in a file.
NOTE: On a *nix platform the withokta
wrapper script will attempt to parse $https_proxy
as a URI. If successful the host and port values will be passed to the JVM. User credentials in the proxy configuration are not currently used. This allows the okta-aws
tool to be used in an environment where internet access for the servers is mediate via a proxy, e.g an EC2 instance inside a restricted VPC.
The proxy URI must be of the form http://host:port/
. Both the host and port are mandatory.
Reference
- okta-listroles(1)
- okta-credential_process(1)
Compiling the application
The application was built and compiled with JetBrains’ IntelliJ IDEA. Note that you don’t have to compile the application in order to be able to execute it, since the compiled executable (a JAR file) is available on GitHub.
Prerequisites
First of all, it goes without saying that you will need to install the Java SE 11x or the Java JDK 11x.
Then you will need Maven 2 or later to run the build.
Building on the command line
Get a single JAR with all dependencies:
Use git clone https://github.com/oktadev/okta-aws-cli-assume-role.git
to clone the repository locally. Then, build with Maven:
mvn package cp target/okta-aws-cli-*.jar ~/.okta/okta-aws-cli.jar
Configuring AWS in Okta
See for details on setting up Amazon Web Services Account Federation to allow logging into AWS through Okta and this tool.
An alternative integration can be found in Integrating the Amazon Web Services Command Line Interface Using Okta, which allows logging into AWS / Okta through the AWS CLI. The okta-aws-cli is not compatible with this integration.
Configuring the application
Here is the list of parameters that can be environment variables or settings in the ~/.okta/config.properties
file:
-
OKTA_ORG
which is the url of your Okta org (starting with https://). -
OKTA_AWS_APP_URL
is the url link of your Okta AWS application url (see below for more info) -
OKTA_USERNAME
is the username to use. If present will skip username input. -
OKTA_PASSWORD_CMD
is the command to fetch your password instead of showing a password prompt. Read more… -
OKTA_ENV_MODE
set to true to run sub-command with AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN env vars set. Temporary credentials are shared in memory and kept off disk in this mode. (default: false) -
OKTA_BROWSER_AUTH
set to true to use integrated web browser for authentication (default: false) -
OKTA_COOKIES_PATH
is directory path to store cookies.properties for Okta. This is particularly useful when running this tool in many concurrent processes like you might with OKTA_ENV_MODE (default: ~/.okta) -
OKTA_PROFILE
is the name of the AWS profile to create/reuse. (default: get AWS profile name based on per-session STS user name) -
OKTA_AWS_REGION
is the default AWS region to store with the created profile. -
OKTA_AWS_ROLE_TO_ASSUME
is the IAM Role ARN to use. If present will try to match okta account’s retrieved role list and use it. Will still prompt if no match found. (ex: arn:aws:iam::123456789012:role/EC2-Admins) -
OKTA_STS_DURATION
is the duration the role will be assumed, in seconds. The maximum session duration allowed by AWS is 12 hours and this needs to be set on the role as well. Defaults to 1hr. -
OKTA_MFA_CHOICE
is the provider and factor type to use if prompted for MFA. Example:OKTA.push
. See Factors documentation for values. (default: use single factor or prompt user to select from usable factors). -
OKTA_IGNORE_SAML_REQ_CONTAIN
is an optional parameter that allow users to ignore parsing SAML requests, where the URL contains a specific string . This is relevant when using the custom IdP factor, which adds additional SAML requests to users authentication flow. See Custom IdP Factor Authentication
for more details. Defaults to an empty string. -
Obtaining the AWS app url
-
Navigate to the
Admin Dashboard
of you Okta organization -
Select the
Applications
tab and click on your AWS Application -
Under the
General
menu, scroll down to find theApp Embed Link
section -
Your link is located under
EMBED LINK
-
Navigate to the
-
Replace the example values in
~/.okta/config.properties
with your values
You can specify configuration overrides…